{"record":{"id":"4b910820639aa4eb","repo":"apache/beam","slug":"unsupported-cdc-metadata-column","errorCode":null,"errorMessage":"Unsupported CDC metadata column: {}","messagePattern":"Unsupported CDC metadata column: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/cdc/IcebergCdcMetadataColumns.java","lineNumber":80,"sourceCode":"  public static boolean isSupportedColumn(String name) {\n    return SUPPORTED_COLUMNS.contains(name);\n  }\n\n  public static boolean isRowMetadataColumn(String name) {\n    return ROW_METADATA_COLUMNS.contains(name);\n  }\n\n  public static Schema.Field beamField(String name) {\n    if (CHANGE_TYPE.equals(name)) {\n      return Schema.Field.of(name, Schema.FieldType.STRING);\n    }\n    if (COMMIT_SNAPSHOT_ID.equals(name) || COMMIT_SNAPSHOT_SEQUENCE_NUMBER.equals(name)) {\n      return Schema.Field.of(name, Schema.FieldType.INT64);\n    }\n    if (ROW_ID.equals(name) || LAST_UPDATED_SEQUENCE_NUMBER.equals(name)) {\n      return Schema.Field.nullable(name, Schema.FieldType.INT64);\n    }\n    throw new IllegalArgumentException(\"Unsupported CDC metadata column: \" + name);\n  }\n\n  /** Returns the Iceberg reader field for row-sourced metadata, or null for commit metadata. */\n  public static Types.@Nullable NestedField icebergRowMetadataField(String name) {\n    if (ROW_ID.equals(name)) {\n      return MetadataColumns.ROW_ID;\n    }\n    if (LAST_UPDATED_SEQUENCE_NUMBER.equals(name)) {\n      return MetadataColumns.LAST_UPDATED_SEQUENCE_NUMBER;\n    }\n    return null;\n  }\n}\n","sourceCodeStart":62,"sourceCodeEnd":94,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/cdc/IcebergCdcMetadataColumns.java#L62-L94","documentation":"IcebergCdcMetadataColumns.beamField maps a CDC metadata column name to its Beam Schema.Field type. Only COMMIT_SNAPSHOT_ID, COMMIT_SNAPSHOT_SEQUENCE_NUMBER, ROW_ID, and LAST_UPDATED_SEQUENCE_NUMBER are supported; any other name throws IllegalArgumentException. This fails fast when a caller requests a metadata column the CDC implementation does not expose.","triggerScenarios":"Calling IcebergCdcMetadataColumns.beamField(name) with a name string that is not one of the four supported metadata column constants — typically a typo, a renamed constant, or a custom column name passed to CDC column configuration.","commonSituations":"Typo in a configured CDC metadata column name; using a metadata column name from Iceberg's MetadataColumns (e.g. ROW_DATA_SEQUENCE_NUMBER) that Beam's CDC layer does not support; upgrading Iceberg and assuming new metadata columns are exposed.","solutions":["Use only the constants defined in IcebergCdcMetadataColumns (COMMIT_SNAPSHOT_ID, COMMIT_SNAPSHOT_SEQUENCE_NUMBER, ROW_ID, LAST_UPDATED_SEQUENCE_NUMBER)","Validate configured column names against the supported set before building the pipeline","Add a mapping in beamField if the column genuinely needs support","Check for typos/case mismatches in the column name"],"exampleFix":"// before\nSchema.Field f = IcebergCdcMetadataColumns.beamField(\"last_updated_snapshot_id\");\n// after\nString name = IcebergCdcMetadataColumns.COMMIT_SNAPSHOT_ID; // use a supported constant\nSchema.Field f = IcebergCdcMetadataColumns.beamField(name);","handlingStrategy":"validation","validationCode":"Set<String> supported = Set.of(IcebergCdcMetadataColumns.COMMIT_SNAPSHOT_ID,\n    IcebergCdcMetadataColumns.COMMIT_SNAPSHOT_SEQUENCE_NUMBER,\n    IcebergCdcMetadataColumns.ROW_ID,\n    IcebergCdcMetadataColumns.LAST_UPDATED_SEQUENCE_NUMBER);\nif (!supported.contains(columnName)) {\n  throw new IllegalArgumentException(\"Unsupported CDC metadata column: \" + columnName);\n}","typeGuard":null,"tryCatchPattern":"try {\n  Schema.Field f = IcebergCdcMetadataColumns.beamField(name);\n} catch (IllegalArgumentException e) {\n  LOG.warn(\"Falling back: {}\", e.getMessage());\n  f = null; // skip optional metadata column\n}","preventionTips":["Always reference the exported constants instead of raw strings","Validate configured column names against the supported set during pipeline setup","Watch for new metadata columns in Iceberg upgrades and check Beam CDC support first"],"tags":["iceberg","cdc","metadata-columns","schema"],"backgroundTag":"invalid-enum-value","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"}