{"record":{"id":"a8b38b1ff7c79ed4","repo":"apache/beam","slug":"unsupported-metadata-column-s-supported-columns-are-s-s-and","errorCode":null,"errorMessage":"Unsupported metadata column %s. Supported columns are: %s, %s, and %s.","messagePattern":"Unsupported metadata column (.+?)\\. Supported columns are: (.+?), (.+?), and (.+?)\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/delta/src/main/java/org/apache/beam/sdk/io/delta/DeltaIO.java","lineNumber":306,"sourceCode":"\n    public ReadChanges withStartTimestamp(String startTimestamp) {\n      return toBuilder().setStartTimestamp(startTimestamp).build();\n    }\n\n    public ReadChanges withEndVersion(long endVersion) {\n      return toBuilder().setEndVersion(endVersion).build();\n    }\n\n    public ReadChanges withEndTimestamp(String endTimestamp) {\n      return toBuilder().setEndTimestamp(endTimestamp).build();\n    }\n\n    public ReadChanges withMetadataColumns(String... metadataColumns) {\n      for (String col : metadataColumns) {\n        if (!col.equals(CHANGE_TYPE_COLUMN)\n            && !col.equals(COMMIT_VERSION_COLUMN)\n            && !col.equals(COMMIT_TIMESTAMP_COLUMN)) {\n          throw new IllegalArgumentException(\n              String.format(\n                  \"Unsupported metadata column %s. Supported columns are: %s, %s, and %s.\",\n                  col, CHANGE_TYPE_COLUMN, COMMIT_VERSION_COLUMN, COMMIT_TIMESTAMP_COLUMN));\n        }\n      }\n      return toBuilder().setMetadataColumns(Arrays.asList(metadataColumns)).build();\n    }\n\n    public ReadChanges withConfig(Map<String, String> config) {\n      return toBuilder().setHadoopConfig(config).build();\n    }\n\n    @Override\n    public PCollection<Row> expand(PBegin input) {\n      String path = getTablePath();\n      if (path == null) {\n        throw new IllegalArgumentException(\"Table path must be set.\");\n      }","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/delta/src/main/java/org/apache/beam/sdk/io/delta/DeltaIO.java#L288-L324","documentation":"DeltaIO.ReadChanges.withMetadataColumns validates each requested metadata column against the three CDF metadata columns the connector supports: _change_type, _commit_version, and _commit_timestamp. Any other name throws IllegalArgumentException with the supported list.","triggerScenarios":"Calling .withMetadataColumns(\"foo\") or passing non-metadata column names (regular table columns, misspelled metadata names like 'commitVersion' or '_commitversion').","commonSituations":"Expecting withMetadataColumns to add business columns (it only selects CDF metadata columns); typos or missing leading underscore; case-sensitivity mistakes.","solutions":["Pass exactly one of the supported names: \"_change_type\", \"_commit_version\", \"_commit_timestamp\".","Business/data columns are always included in the output — do not list them via withMetadataColumns.","Check spelling and the leading underscore; names are case-sensitive string comparisons.","If you need a metadata column that isn't supported, read without it and derive it (e.g. from the source) in your own transform."],"exampleFix":"// before\nDeltaIO.read().from(path).readChanges().withMetadataColumns(\"commit_version\", \"user_col\");\n// after\nDeltaIO.read().from(path).readChanges().withMetadataColumns(\"_commit_version\", \"_commit_timestamp\");","handlingStrategy":"validation","validationCode":"java.util.Set<String> ALLOWED = java.util.Set.of(\"_change_type\", \"_commit_version\", \"_commit_timestamp\");\nfor (String c : requestedMetadataColumns) { if (!ALLOWED.contains(c)) throw new IllegalArgumentException(\"Unsupported metadata column: \" + c); }","typeGuard":"static boolean isMetadataColumn(String col) {\n  return java.util.Set.of(\"_change_type\", \"_commit_version\", \"_commit_timestamp\").contains(col);\n}","tryCatchPattern":"try { transform = read.readChanges().withMetadataColumns(cols); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Unsupported metadata column\")) { fixColumnNames(); } else { throw e; } }","preventionTips":["Use the DeltaIO.CHANGE_TYPE_COLUMN / COMMIT_VERSION_COLUMN / COMMIT_TIMESTAMP_COLUMN constants instead of string literals.","Remember withMetadataColumns only selects CDF metadata columns — data columns are always present.","Validate requested column names against the constant set before building the transform."],"tags":["java","delta-lake","cdc","argument-validation","metadata-columns"],"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-14T16:17:12.679Z"}