{"record":{"id":"9ab5355cc4d0a454","repo":"apache/beam","slug":"resolved-references-multiple-fields","errorCode":null,"errorMessage":"${resolved} references multiple fields.","messagePattern":"(.+?) references multiple fields\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/RenameFields.java","lineNumber":87,"sourceCode":"\n  // Describes a single renameSchema rule\n  @AutoValue\n  abstract static class RenamePair implements Serializable {\n    // The FieldAccessDescriptor describing the field to renameSchema. Must reference a singleton\n    // field.\n    abstract FieldAccessDescriptor getFieldAccessDescriptor();\n\n    // The new name for the field.\n    abstract String getNewName();\n\n    static RenamePair of(FieldAccessDescriptor fieldAccessDescriptor, String newName) {\n      return new AutoValue_RenameFields_RenamePair(fieldAccessDescriptor, newName);\n    }\n\n    RenamePair resolve(Schema schema) {\n      FieldAccessDescriptor resolved = getFieldAccessDescriptor().resolve(schema);\n      if (!resolved.referencesSingleField()) {\n        throw new IllegalArgumentException(resolved + \" references multiple fields.\");\n      }\n      return RenamePair.of(resolved, getNewName());\n    }\n  }\n\n  private static FieldType renameFieldType(\n      FieldType inputType,\n      Collection<RenamePair> renames,\n      Map<UUID, Schema> renamedSchemasMap,\n      Map<UUID, BitSet> nestedFieldRenamedMap) {\n    if (renames.isEmpty()) {\n      return inputType;\n    }\n\n    switch (inputType.getTypeName()) {\n      case ROW:\n        renameSchema(inputType.getRowSchema(), renames, renamedSchemasMap, nestedFieldRenamedMap);\n        return FieldType.row(renamedSchemasMap.get(inputType.getRowSchema().getUUID()));","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/RenameFields.java#L69-L105","documentation":"RenameFields renames exactly one field per RenamePair. After resolving the FieldAccessDescriptor against the schema, if it references multiple fields (e.g. a wildcard, qualifier matching several fields, or a multi-field descriptor), resolve() throws IllegalArgumentException since a rename must map a single field to a new name.","triggerScenarios":"Building RenameField.create(...) with a FieldAccessDescriptor matching more than one field — e.g. By.field(\"a.*\")-style or descriptors built with multiple fields via FieldAccessDescriptor.withFieldNames(\"a\",\"b\").","commonSituations":"Using a wildcard-ish or shared-prefix field spec expecting all matched fields to be renamed, or passing a multi-field descriptor to a single rename call instead of one rename per field.","solutions":["Create one RenameField per field: withRenamedField(\"a\", \"newA\").withRenamedField(\"b\", \"newB\").","Narrow the FieldAccessDescriptor so it references exactly one field (use referencesSingleField to check).","Avoid wildcard/multi-field descriptors in rename specifications.","Resolve the descriptor against the schema in tests before running the pipeline to catch multi-field matches early."],"exampleFix":"// before\nRenameFields.of(RenamePair.of(FieldAccessDescriptor.withFieldNames(\"a\",\"b\"), \"x\"))\n// after\nRenameFields.of(RenamePair.of(FieldAccessDescriptor.withFieldNames(\"a\"), \"x\"))\n            .and(RenamePair.of(FieldAccessDescriptor.withFieldNames(\"b\"), \"y\"))","handlingStrategy":"validation","validationCode":"FieldAccessDescriptor r = desc.resolve(schema); if (!r.referencesSingleField()) throw new IllegalArgumentException(\"Rename must reference exactly one field, got: \" + r);","typeGuard":"boolean singleField(FieldAccessDescriptor d, Schema s) { return d.resolve(s).referencesSingleField(); }","tryCatchPattern":"try { pairs.resolve(schema); } catch (IllegalArgumentException e) { if (e.getMessage().endsWith(\"references multiple fields.\")) { /* split the descriptor into per-field renames */ } throw e; }","preventionTips":["One rename pair per field — never reuse a multi-field descriptor","Test resolve() against the real schema before deploying","Avoid wildcard field specifications in renames"],"tags":["java","apache-beam","rename-fields","field-descriptor"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}