apache/beam · error · IllegalArgumentException

Unsupported change type:

Error message

Unsupported change type: 

What it means

DeltaCDCSourceDoFn.getValueKind maps the _change_type string to a Beam ValueKind (INSERT/DELETE/UPDATE_BEFORE/UPDATE_AFTER). Any value outside the Delta CDF enum (insert, delete, update_preimage, update_postimage) hits the default branch and throws IllegalArgumentException.

Source

Thrown at sdks/java/io/delta/src/main/java/org/apache/beam/sdk/io/delta/DeltaCDCSourceDoFn.java:272

      builder.addValue(value);
    }
    return builder.build();
  }

  private static ValueKind getValueKind(String changeType) {
    // Maps Delta CDC change types to Beam's ValueKind enum.
    // https://docs.delta.io/delta-change-data-feed/#what-is-the-schema-for-the-change-data-feed
    switch (changeType) {
      case "insert":
        return ValueKind.INSERT;
      case "delete":
        return ValueKind.DELETE;
      case "update_preimage":
        return ValueKind.UPDATE_BEFORE;
      case "update_postimage":
        return ValueKind.UPDATE_AFTER;
      default:
        throw new IllegalArgumentException("Unsupported change type: " + changeType);
    }
  }

  private static StructType appendCDFColumns(StructType schema) {
    return schema
        .add(DeltaIO.CHANGE_TYPE_COLUMN, StringType.STRING, true)
        .add(DeltaIO.COMMIT_VERSION_COLUMN, LongType.LONG, true)
        .add(DeltaIO.COMMIT_TIMESTAMP_COLUMN, TimestampType.TIMESTAMP, true);
  }

  private ColumnarBatch appendConstantCDFColumns(
      Engine engine, ColumnarBatch batch, long version, long timestamp) {
    StructType schemaForEval = batch.getSchema();

    ExpressionEvaluator changeTypeGenerator =
        wrapEngineException(
            () ->
                engine

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam delta-io connector to a version that supports the change type your Delta writer emits.
2. Inspect the offending _change_type values in the table (SELECT DISTINCT _change_type ...) to see what unexpected value exists.
3. Normalize the value (lowercase/trim) at the writer side if custom code produces CDF metadata.
4. As a stopgap, add a case for the new change type or pre-filter such rows in a prior transform.

Example fix

// before
switch (changeType) {
  case "insert": ... case "delete": ... // missing newer types
  default: throw new IllegalArgumentException("Unsupported change type: " + changeType);
}
// after
// upgrade the connector, or normalize:
String ct = changeType == null ? null : changeType.trim().toLowerCase();
switch (ct) { /* existing cases plus any new Delta change types */ }

java.util.Set<String> KNOWN = java.util.Set.of("insert","delete","update_preimage","update_postimage");
// before reading: SELECT DISTINCT _change_type FROM table_changes(...) and check all values are in KNOWN

static boolean isKnownChangeType(String changeType) {
  return changeType != null && java.util.Set.of("insert","delete","update_preimage","update_postimage").contains(changeType.trim().toLowerCase());
}

try { /* process CDC rows */ } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unsupported change type:")) { logOffendingRowsAndUpgradeConnector(); } else { throw e; } }

When it happens

Trigger: A row's _change_type contains an unexpected string — a newer Delta writer version emitting new change types, a hand-edited/corrupted _change_type value, or case differences from custom writes.

Common situations: Upgrading Delta writers that introduce change types this Beam connector doesn't know; writing CDF metadata columns manually with wrong casing; data corrupted by a non-Delta writer touching the table.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Starting version or timestamp must be specified.
• Resolved start version %d is greater than resolved end versi
• Field must not be null.
• Unsupported metadata column %s. Supported columns are: %s, %
• Unsupported CDC ValueKind: {}

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