{"record":{"id":"5ca7e90897098355","repo":"apache/beam","slug":"reserved-field-name-s-in-user-schema","errorCode":null,"errorMessage":"Reserved field name %s in user schema.","messagePattern":"Reserved field name (.+?) in user schema\\.","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/TableRowToStorageApiProto.java","lineNumber":1324,"sourceCode":"\n      fieldDescriptorBuilder = FieldDescriptorProto.newBuilder();\n      fieldDescriptorBuilder = fieldDescriptorBuilder.setName(StorageApiCDC.CHANGE_SQN_COLUMN);\n      fieldDescriptorBuilder = fieldDescriptorBuilder.setNumber(i++);\n      fieldDescriptorBuilder =\n          fieldDescriptorBuilder.setType(FieldDescriptorProto.Type.TYPE_STRING);\n      fieldDescriptorBuilder = fieldDescriptorBuilder.setLabel(Label.LABEL_OPTIONAL);\n      descriptorBuilder.addField(fieldDescriptorBuilder.build());\n    }\n    return descriptorBuilder.build();\n  }\n\n  private static void fieldDescriptorFromTableField(\n      TableFieldSchema fieldSchema,\n      int fieldNumber,\n      DescriptorProto.Builder descriptorBuilder,\n      boolean respectRequired) {\n    if (StorageApiCDC.COLUMNS.contains(fieldSchema.getName())) {\n      throw new RuntimeException(\n          \"Reserved field name \" + fieldSchema.getName() + \" in user schema.\");\n    }\n    FieldDescriptorProto.Builder fieldDescriptorBuilder = FieldDescriptorProto.newBuilder();\n    final String fieldName = fieldSchema.getName().toLowerCase();\n    fieldDescriptorBuilder = fieldDescriptorBuilder.setName(fieldName);\n    fieldDescriptorBuilder = fieldDescriptorBuilder.setNumber(fieldNumber);\n    if (!BigQuerySchemaUtil.isProtoCompatible(fieldName)) {\n      fieldDescriptorBuilder =\n          fieldDescriptorBuilder.setName(\n              BigQuerySchemaUtil.generatePlaceholderFieldName(fieldName));\n\n      Message.Builder fieldOptionBuilder = DescriptorProtos.FieldOptions.newBuilder();\n      fieldOptionBuilder =\n          fieldOptionBuilder.setField(AnnotationsProto.columnName.getDescriptor(), fieldName);\n      fieldDescriptorBuilder =\n          fieldDescriptorBuilder.setOptions(\n              (DescriptorProtos.FieldOptions) fieldOptionBuilder.build());\n    }","sourceCodeStart":1306,"sourceCodeEnd":1342,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/TableRowToStorageApiProto.java#L1306-L1342","documentation":"BigQuery Storage API CDC reserves certain column names (e.g. StorageApiCDC.COLUMNS). A user-supplied TableFieldSchema using one of these reserved names cannot be converted into a proto descriptor and fails fast with a RuntimeException.","triggerScenarios":"Defining a BigQuery sink schema that includes a field whose name collides with reserved CDC columns (record_name, record_index, changed_fields / the entries in StorageApiDirtyDataHoldingRecord / StorageApiCDC.COLUMNS) while using Storage API writes with CDC enabled.","commonSituations":"Ingesting upstream data that already has a column literally named like the CDC metadata column; adding a column called e.g. 'record_name' after CDC output exists in the same table.","solutions":["Rename the offending column in your schema and data to something not in StorageApiCDC.COLUMNS.","Alias the column during extract/transform (e.g. withColumnRenamed / select with an alias).","Disable CDC (disableStreamingSideInputs / no-CDC write mode) if you cannot rename and don't need it."],"exampleFix":"// before\nTableFieldSchema.newBuilder().setName(\"record_name\")...\n// after\nTableFieldSchema.newBuilder().setName(\"source_record_name\")...","handlingStrategy":"validation","validationCode":"if (StorageApiCDC.COLUMNS.contains(fieldName)) { throw new IllegalArgumentException(\"Field \" + fieldName + \" collides with reserved CDC column\"); }","typeGuard":"boolean isAllowedUserField(String name) { return !StorageApiCDC.COLUMNS.contains(name); }","tryCatchPattern":"try { buildDescriptor(schema); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Reserved field name\")) renameAndRetry(); else throw e; }","preventionTips":["Check StorageApiCDC.COLUMNS before adding any column to a CDC-enabled sink schema","Use a prefix (e.g. src_) for columns coming from external systems","Review schema diffs for newly added columns that could collide with reserved names"],"tags":["bigquery","cdc","naming-conflict","java"],"backgroundTag":"invalid-identifier-format","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"}