apache/beam · error · IllegalArgumentException

Unsupported metadata column %s. Supported columns are: %s, %

Error message

Unsupported metadata column %s. Supported columns are: %s, %s, and %s.

What it means

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.

Source

Thrown at sdks/java/io/delta/src/main/java/org/apache/beam/sdk/io/delta/DeltaIO.java:306

    public ReadChanges withStartTimestamp(String startTimestamp) {
      return toBuilder().setStartTimestamp(startTimestamp).build();
    }

    public ReadChanges withEndVersion(long endVersion) {
      return toBuilder().setEndVersion(endVersion).build();
    }

    public ReadChanges withEndTimestamp(String endTimestamp) {
      return toBuilder().setEndTimestamp(endTimestamp).build();
    }

    public ReadChanges withMetadataColumns(String... metadataColumns) {
      for (String col : metadataColumns) {
        if (!col.equals(CHANGE_TYPE_COLUMN)
            && !col.equals(COMMIT_VERSION_COLUMN)
            && !col.equals(COMMIT_TIMESTAMP_COLUMN)) {
          throw new IllegalArgumentException(
              String.format(
                  "Unsupported metadata column %s. Supported columns are: %s, %s, and %s.",
                  col, CHANGE_TYPE_COLUMN, COMMIT_VERSION_COLUMN, COMMIT_TIMESTAMP_COLUMN));
        }
      }
      return toBuilder().setMetadataColumns(Arrays.asList(metadataColumns)).build();
    }

    public ReadChanges withConfig(Map<String, String> config) {
      return toBuilder().setHadoopConfig(config).build();
    }

    @Override
    public PCollection<Row> expand(PBegin input) {
      String path = getTablePath();
      if (path == null) {
        throw new IllegalArgumentException("Table path must be set.");
      }

View on GitHub (pinned to 12126d8942)

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.

Example fix

// before
DeltaIO.read().from(path).readChanges().withMetadataColumns("commit_version", "user_col");
// after
DeltaIO.read().from(path).readChanges().withMetadataColumns("_commit_version", "_commit_timestamp");

Defensive patterns

Strategy: validation

Validate before calling

java.util.Set<String> ALLOWED = java.util.Set.of("_change_type", "_commit_version", "_commit_timestamp");
for (String c : requestedMetadataColumns) { if (!ALLOWED.contains(c)) throw new IllegalArgumentException("Unsupported metadata column: " + c); }

Type guard

static boolean isMetadataColumn(String col) {
  return java.util.Set.of("_change_type", "_commit_version", "_commit_timestamp").contains(col);
}

Try / catch

try { transform = read.readChanges().withMetadataColumns(cols); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unsupported metadata column")) { fixColumnNames(); } else { throw e; } }

Prevention

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.

When it happens

Trigger: Calling .withMetadataColumns("foo") or passing non-metadata column names (regular table columns, misspelled metadata names like 'commitVersion' or '_commitversion').

Common situations: Expecting withMetadataColumns to add business columns (it only selects CDF metadata columns); typos or missing leading underscore; case-sensitivity mistakes.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/a8b38b1ff7c79ed4. Report an issue: GitHub.