What causes "Cannot apply unknown table change: ${change}" in apache/iceberg?

Upgrade iceberg-spark to a version matching your Spark version so all change types are handled

apache/iceberg · error · UnsupportedOperationException

Cannot apply unknown table change

Error message

Cannot apply unknown table change: ${change}

What it means

SparkCatalog.alterTable maps Spark UpdateTableStatement changes to Iceberg commit types (SetProperty, RemoveProperty, ColumnChange, plus special-cased location/snapshot changes). A change object of an unrecognized type cannot be applied, so it throws UnsupportedOperationException listing the change.

Solutions

Upgrade iceberg-spark to a version matching your Spark version so all change types are handled
Inspect the failing change's class and convert it to a supported change (SetProperty/RemoveProperty/ColumnChange)
Avoid custom TableChange subclasses; use Spark SQL statements that generate supported changes

Example fix

// before
TableChange custom = new MyCustomChange();
catalog.alterTable(ident, custom); // throws
// after
catalog.alterTable(ident, TableChange.setProperty("write.format.default", "parquet"));

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try { sparkCatalog.alterTable(ident, changes); } catch (UnsupportedOperationException e) { log.error("Unsupported table change, check iceberg-spark/Spark version alignment", e); throw e; }

Prevention

Keep iceberg-spark version matched to your Spark version
Only use standard Spark SQL statements to generate TableChanges
Avoid custom TableChange subclasses

When it happens

Trigger: Calling SparkCatalog.alterTable(Identifier, TableChange[]) with a TableChange implementation outside the handled set — typically a custom TableChange subclass or a Spark change type added in a newer Spark version than the bundled Iceberg SparkCatalog supports.

Common situations: Spark/Iceberg version mismatch introducing new change kinds (e.g. newer Spark option-change types); custom engine integrations crafting their own TableChange implementations; test code passing unsupported changes.

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

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

Appendix: source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:336

        } 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);
    } 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)