{"record":{"id":"93b76789c564e20a","repo":"apache/beam","slug":"reserved-field-name-field-getname-in-user-schema","errorCode":null,"errorMessage":"Reserved field name \" + field.getName() + \" in user schema.","messagePattern":"Reserved field name \" \\+ field\\.getName\\(\\) \\+ \" in user schema\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BeamRowToStorageApiProto.java","lineNumber":206,"sourceCode":"    }\n    return builder.build();\n  }\n\n  @VisibleForTesting\n  static TableSchema protoTableSchemaFromBeamSchema(Schema schema) {\n    Preconditions.checkState(schema.getFieldCount() > 0);\n\n    TableSchema.Builder builder = TableSchema.newBuilder();\n    for (Field field : schema.getFields()) {\n      builder.addFields(fieldDescriptorFromBeamField(field));\n    }\n    return builder.build();\n  }\n\n  private static TableFieldSchema fieldDescriptorFromBeamField(Field field) {\n    TableFieldSchema.Builder builder = TableFieldSchema.newBuilder();\n    if (StorageApiCDC.COLUMNS.contains(field.getName())) {\n      throw new RuntimeException(\"Reserved field name \" + field.getName() + \" in user schema.\");\n    }\n    builder = builder.setName(field.getName().toLowerCase());\n\n    switch (field.getType().getTypeName()) {\n      case ROW:\n        @Nullable Schema rowSchema = field.getType().getRowSchema();\n        if (rowSchema == null) {\n          throw new RuntimeException(\"Unexpected null schema!\");\n        }\n        builder = builder.setType(TableFieldSchema.Type.STRUCT);\n        for (Schema.Field nestedField : rowSchema.getFields()) {\n          builder = builder.addFields(fieldDescriptorFromBeamField(nestedField));\n        }\n        break;\n      case ARRAY:\n      case ITERABLE:\n        @Nullable FieldType elementType = field.getType().getCollectionElementType();\n        if (elementType == null) {","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BeamRowToStorageApiProto.java#L188-L224","documentation":"fieldDescriptorFromBeamField rejects Beam Schema fields whose names collide with the reserved Storage API CDC columns (StorageApiCDC.COLUMNS, e.g. \"record_number\", \"replay\", \"modified_time\"). Since BigQuery appends CDC metadata columns internally, a user field with such a name would conflict, so a RuntimeException is thrown.","triggerScenarios":"Writing a Beam Row schema to BigQuery via Storage API (especially with CDC enabled) where any field — including nested fields — is named like a reserved CDC column","commonSituations":"Schemas derived from external tables that happen to have a column named record_number or modified_time; auto-generated schemas from JSON/CSV headers containing these names.","solutions":["Rename the field in your Beam Schema to something not in StorageApiCDC.COLUMNS (e.g. recordNumber or record_num)","Rename the column at the data source level before building the schema","Check StorageApiCDC.COLUMNS in the Beam source to see the exact reserved names","If renaming is impossible, write to a non-CDC sink or stage the data through a rename step"],"exampleFix":"// before\nSchema schema = Schema.builder().addInt64Field(\"record_number\").build();\n// after\nSchema schema = Schema.builder().addInt64Field(\"record_num\").build();","handlingStrategy":"validation","validationCode":"// Java\nfor (Schema.Field f : beamSchema.getFields()) {\n  if (StorageApiCDC.COLUMNS.contains(f.getName())) {\n    throw new IllegalStateException(\"Reserved CDC column name: \" + f.getName());\n  }\n}","typeGuard":"// Java\nboolean reserved = StorageApiCDC.COLUMNS.contains(fieldName); // check before adding field","tryCatchPattern":"// Java\ntry {\n  schema = BeamRowToStorageApiProto.protoTableSchemaFromBeamSchema(beamSchema);\n} catch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Reserved field name\")) {\n    // rename offending column and rebuild schema\n  }\n  throw e;\n}","preventionTips":["Check field names against StorageApiCDC.COLUMNS when building schemas","Sanitize external column headers (CSV/JSON) before schema creation","Add a unit test asserting no schema field collides with CDC reserved names"],"tags":["java","bigquery","beam-schema","naming"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}