apache/iceberg · error · UnsupportedOperationException

Cannot apply unknown table change: {change}

Error message

Cannot apply unknown table change: {change}

What it means

Catch-all branch of applySchemaChanges: a TableChange subtype not recognized by the if/else chain is rejected with UnsupportedOperationException. It indicates the Flink change type has no Iceberg mapping in this connector version.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/util/FlinkAlterTableUtil.java:149

      } else if (change instanceof TableChange.DropColumn) {
        TableChange.DropColumn dropColumn = (TableChange.DropColumn) change;
        pendingUpdate.deleteColumn(dropColumn.getColumnName());
      } else if (change instanceof TableChange.AddWatermark) {
        throw new UnsupportedOperationException("Unsupported table change: AddWatermark.");
      } else if (change instanceof TableChange.ModifyWatermark) {
        throw new UnsupportedOperationException("Unsupported table change: ModifyWatermark.");
      } else if (change instanceof TableChange.DropWatermark) {
        throw new UnsupportedOperationException("Unsupported table change: DropWatermark.");
      } else if (change instanceof TableChange.AddUniqueConstraint) {
        TableChange.AddUniqueConstraint addPk = (TableChange.AddUniqueConstraint) change;
        applyUniqueConstraint(pendingUpdate, addPk.getConstraint());
      } else if (change instanceof TableChange.ModifyUniqueConstraint) {
        TableChange.ModifyUniqueConstraint modifyPk = (TableChange.ModifyUniqueConstraint) change;
        applyUniqueConstraint(pendingUpdate, modifyPk.getNewConstraint());
      } else if (change instanceof TableChange.DropConstraint) {
        throw new UnsupportedOperationException("Unsupported table change: DropConstraint.");
      } else {
        throw new UnsupportedOperationException("Cannot apply unknown table change: " + change);
      }
    }
  }

  private static void applyAddColumn(UpdateSchema pendingUpdate, TableChange.AddColumn addColumn) {
    Column flinkColumn = addColumn.getColumn();
    Preconditions.checkArgument(
        FlinkCompatibilityUtil.isPhysicalColumn(flinkColumn),
        "Unsupported table change: Adding computed column %s.",
        flinkColumn.getName());

    Type icebergType = FlinkSchemaUtil.convert(flinkColumn.getDataType().getLogicalType());

    if (flinkColumn.getDataType().getLogicalType().isNullable()) {
      pendingUpdate.addColumn(
          flinkColumn.getName(), icebergType, flinkColumn.getComment().orElse(null));
    } else {
      pendingUpdate.addRequiredColumn(

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the iceberg-flink connector to a version matching your Flink version so the change type is handled
2. Check which TableChange subtype you send (log/change.getClass().getName()) and replace it with a supported one
3. Apply the schema change via Iceberg's native API (UpdateSchema) instead of Flink DDL

Example fix

// before
change = TableChange.SomeNewChange(...); catalog.applyChange(tableId, change);
// after
// upgrade connector or use: table.updateSchema().<appropriate op>().commit();

// whitelist known change types before applying
Set<Class<?>> supported = Set.of(TableChange.AddColumn.class, TableChange.ModifyColumn.class, TableChange.DropColumn.class, TableChange.SetOption.class, TableChange.ResetOption.class);

try {
  FlinkAlterTableUtil.applySchemaChanges(update, changes);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Cannot apply unknown table change")) {
    log.error("Unmapped TableChange subtype: {}", changes.getClass(), e);
  }
  throw e;
}

When it happens

Trigger: Passing any TableChange other than Add/Modify/Drop column, watermark changes, unique/primary-key constraint changes, or SetOption/ResetOption to applySchemaChanges — typically a new Flink TableChange type introduced in a newer Flink version.

Common situations: Using a Flink 1.18+ or 2.x TableChange subtype with an Iceberg connector built for an older Flink API; custom catalog implementations forwarding unknown change objects.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsupported table change: AddWatermark.
• Unsupported table change: ModifyWatermark.
• Unsupported table change: DropWatermark.
• Unsupported table change: DropConstraint.
• Cannot apply unknown modify-column change: {modifyColumn}

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/7bf7a9c6227fa9cf. Report an issue: GitHub.