apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot apply unknown table change: %s

Error message

Cannot apply unknown table change: %s

What it means

Spark's alterTable receives a list of TableChange objects; SparkCatalog maps recognized types (SetProperty/RemoveProperty/ColumnChange) to Iceberg operations. Any other TableChange subtype has no Iceberg equivalent, so alterTable throws this UnsupportedOperationException at line 356.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:356

        } 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. Check that only supported changes are issued (properties and column changes).
2. Upgrade the iceberg-spark runtime to a version matching your Spark minor version so new TableChange types are mapped.
3. Split the operation into supported SET/REMOVE PROPERTY and column changes.
4. Submit an issue/patch to Iceberg to handle the new TableChange type.

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

null

try { catalog.alterTable(ident, changes); } catch (UnsupportedOperationException e) { log.error("TableChange {} not supported", e.getMessage()); }

When it happens

Trigger: Calling Spark's catalog.alterTable with an unhandled org.apache.spark.sql.connector.catalog.TableChange subclass (neither SetProperty, RemoveProperty, nor a ColumnChange); future/Custom TableChange implementations introduced by plugins or newer Spark versions not yet mapped by this SparkCatalog.

Common situations: Using a Spark version or extension that emits new TableChange types the vendored Iceberg v3.5 connector does not understand; custom catalog integrations passing through bespoke changes; library version mismatch between Spark and Iceberg runtime.

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:
• 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/e854c4f6f118d76c. Report an issue: GitHub.