apache/iceberg · error · UnsupportedOperationException

Cannot apply unknown table change:

Error message

Cannot apply unknown table change: 

What it means

SparkCatalog.alterTable categorizes each TableChange into property and schema changes; a change type outside SetProperty/RemoveProperty/ColumnChange cannot be applied to an Iceberg table and throws UnsupportedOperationException naming the change object.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:357

        } else if ("cherry-pick-snapshot-id".equalsIgnoreCase(set.property())) {
          pickSnapshotId = set;
        } else if ("sort-order".equalsIgnoreCase(set.property())) {
          throw new UnsupportedOperationException(
              "Cannot specify the 'sort-order' because it's a reserved table "
                  + "property. Please use the command 'ALTER TABLE ... WRITE ORDERED BY' to specify write sort-orders.");
        } else if ("identifier-fields".equalsIgnoreCase(set.property())) {
          throw new UnsupportedOperationException(
              "Cannot specify the 'identifier-fields' because it's a reserved table property. "
                  + "Please use the command 'ALTER TABLE ... SET IDENTIFIER FIELDS' to specify identifier fields.");
        } else {
          propertyChanges.add(set);
        }
      } else if (change instanceof RemoveProperty) {
        propertyChanges.add(change);
      } else if (change instanceof ColumnChange) {
        schemaChanges.add(change);
      } else {
        throw new UnsupportedOperationException("Cannot apply unknown table change: " + change);
      }
    }

    try {
      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));
      commitChanges(
          table, setLocation, setSnapshotId, pickSnapshotId, propertyChanges, schemaChanges);
      return new SparkTable(table, true /* refreshEagerly */);
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      throw new NoSuchTableException(ident);
    }
  }

  @Override
  public boolean dropTable(Identifier ident) {
    return catalogDropTable(ident);
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Restrict alterTable calls to supported changes: SetProperty, RemoveProperty, and ColumnChange (AddColumn, UpdateColumnComment, etc.).
2. Align Spark and Iceberg versions so all engine TableChange types are recognized by the integration.
3. If a new Spark change type is needed, upgrade Iceberg or implement handling in a custom catalog subclass.
4. Log/print the change object named in the message to identify the unsupported type.

for (TableChange change : changes) {
  if (!(change instanceof SetProperty || change instanceof RemoveProperty
      || change instanceof ColumnChange)) {
    throw new IllegalArgumentException("Unsupported change type: " + change.getClass().getName());
  }
}

boolean isSupportedChange(TableChange c) {
  return c instanceof SetProperty || c instanceof RemoveProperty || c instanceof ColumnChange;
}

try {
  catalog.alterTable(ident, changes);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Cannot apply unknown table change")) {
    LOG.error("Unsupported TableChange: {}", e.getMessage());
  }
  throw e;
}

When it happens

Trigger: Passing an unsupported Spark TableChange subclass (neither a property nor a column change) into catalog.alterTable(ident, change) — e.g. custom TableChange implementations or Spark engine changes adding new change types not yet mapped.

Common situations: Calling the V2 catalog alterTable API programmatically with hand-built TableChange objects; Spark version skew where newer change types are passed to an older Iceberg Spark integration; custom CatalogPlugin wrappers injecting their own change types.

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

• Cannot apply unknown table change: %s
• Cannot specify the 'sort-order' because it's a reserved tabl
• Cannot specify the 'identifier-fields' because it's a reserv
• Cannot specify the 'sort-order' because it's a reserved tabl
• Cannot specify the 'identifier-fields' because it's a reserv

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