{"record":{"id":"087dc987ea4d875c","repo":"apache/beam","slug":"reserved-field-name-field-name-in-user-schema","errorCode":null,"errorMessage":"Reserved field name <field.name()> in user schema.","messagePattern":"Reserved field name <field\\.name\\(\\)> 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/AvroGenericRecordToStorageApiProto.java","lineNumber":325,"sourceCode":"    if (changeType != null) {\n      builder.setField(\n          org.apache.beam.sdk.util.Preconditions.checkStateNotNull(\n              descriptor.findFieldByName(StorageApiCDC.CHANGE_TYPE_COLUMN)),\n          changeType);\n      builder.setField(\n          org.apache.beam.sdk.util.Preconditions.checkStateNotNull(\n              descriptor.findFieldByName(StorageApiCDC.CHANGE_SQN_COLUMN)),\n          org.apache.beam.sdk.util.Preconditions.checkStateNotNull(changeSequenceNum));\n    }\n    return builder.build();\n  }\n\n  private static TableFieldSchema fieldDescriptorFromAvroField(org.apache.avro.Schema.Field field) {\n    @Nullable Schema schema = field.schema();\n\n    Preconditions.checkNotNull(schema, \"Unexpected null schema!\");\n    if (StorageApiCDC.COLUMNS.contains(field.name())) {\n      throw new RuntimeException(\"Reserved field name \" + field.name() + \" in user schema.\");\n    }\n    TableFieldSchema.Builder builder =\n        TableFieldSchema.newBuilder().setName(field.name().toLowerCase());\n    Schema elementType = null;\n    switch (schema.getType()) {\n      case RECORD:\n        Preconditions.checkState(!schema.getFields().isEmpty());\n        builder = builder.setType(TableFieldSchema.Type.STRUCT);\n        for (Schema.Field recordField : schema.getFields()) {\n          builder = builder.addFields(fieldDescriptorFromAvroField(recordField));\n        }\n        break;\n      case ARRAY:\n        elementType = TypeWithNullability.create(schema.getElementType()).getType();\n        if (elementType == null) {\n          throw new RuntimeException(\"Unexpected null element type!\");\n        }\n        Preconditions.checkState(","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/AvroGenericRecordToStorageApiProto.java#L307-L343","documentation":"When converting an Avro schema to a BigQuery Storage API TableSchema, fields whose names collide with StorageApiCDC reserved column names are rejected with RuntimeException 'Reserved field name X in user schema.' BigQuery CDC metadata columns must not be shadowed by user fields.","triggerScenarios":"AvroGenericRecordToStorageApiProto.fieldDescriptorFromAvroField encountering an Avro field whose name is in StorageApiCDC.COLUMNS while building the table schema for a Storage Write API sink.","commonSituations":"Using a CDC-enabled BigQuery table while the source Avro schema contains columns like the CDC reserved names; schema drift after enabling StorageApiCDC.","solutions":["Rename the Avro field so it no longer collides with StorageApiCDC reserved names","Remove the reserved field from the schema if it is not needed","Disable/move CDC usage so the column names are allowed"],"exampleFix":"// before\n{\"name\": \"<reserved_cdc_column>\", \"type\": \"string\"}\n// after\n{\"name\": \"user_<reserved_cdc_column>\", \"type\": \"string\"} // renamed to avoid collision","handlingStrategy":"validation","validationCode":"for (org.apache.avro.Schema.Field f : avroSchema.getFields()) { if (StorageApiCDC.COLUMNS.contains(f.name())) throw new IllegalStateException(\"reserved field: \" + f.name()); }","typeGuard":"boolean hasNoCdcReservedNames(org.apache.avro.Schema s) { return s.getFields().stream().noneMatch(f -> StorageApiCDC.COLUMNS.contains(f.name())); }","tryCatchPattern":"try { protoTableSchema = AvroGenericRecordToStorageApiProto.protoTableSchemaFromAvroSchema(schema, true); } catch (RuntimeException e) { if (e.getMessage().contains(\"Reserved field name\")) { renameAndRetry(); } else throw e; }","preventionTips":["Check schemas against StorageApiCDC.COLUMNS at ingestion time","Namespace user columns to avoid collisions","Re-validate schemas after enabling CDC on a table"],"tags":["java","apache-beam","bigquery","avro","schema"],"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-14T16:17:12.679Z"}