apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot apply unknown table change: <change>

Error message

Cannot apply unknown table change: <change>

What it means

Spark3Util.applyPropertyChanges applies Spark DDL table property changes to an Iceberg PendingUpdate. Any TableChange that is not SetProperty or RemoveProperty reaches this final else branch, and the library refuses to guess its intent, throwing UnsupportedOperationException with the change description.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:152

   * Applies a list of Spark table changes to an {@link UpdateProperties} operation.
   *
   * @param pendingUpdate an uncommitted UpdateProperties operation to configure
   * @param changes a list of Spark table changes
   * @return the UpdateProperties operation configured with the changes
   */
  public static UpdateProperties applyPropertyChanges(
      UpdateProperties pendingUpdate, List<TableChange> changes) {
    for (TableChange change : changes) {
      if (change instanceof TableChange.SetProperty) {
        TableChange.SetProperty set = (TableChange.SetProperty) change;
        pendingUpdate.set(set.property(), set.value());

      } else if (change instanceof TableChange.RemoveProperty) {
        TableChange.RemoveProperty remove = (TableChange.RemoveProperty) change;
        pendingUpdate.remove(remove.property());

      } else {
        throw new UnsupportedOperationException("Cannot apply unknown table change: " + change);
      }
    }

    return pendingUpdate;
  }

  /**
   * Applies a list of Spark table changes to an {@link UpdateSchema} operation.
   *
   * @param pendingUpdate an uncommitted UpdateSchema operation to configure
   * @param changes a list of Spark table changes
   * @return the UpdateSchema operation configured with the changes
   */
  public static UpdateSchema applySchemaChanges(
      UpdateSchema pendingUpdate, List<TableChange> changes) {
    for (TableChange change : changes) {
      if (change instanceof TableChange.AddColumn) {
        apply(pendingUpdate, (TableChange.AddColumn) change);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Only pass property-type changes (SetProperty/RemoveProperty) to applyPropertyChanges; route column changes through applySchemaChanges
2. Add a case for the missing TableChange subtype before calling this method, handling it via pendingUpdate explicitly
3. Check the Iceberg/Spark version pairing — new TableChange types may need a newer Iceberg build

Example fix

// before
Spark3Util.applyPropertyChanges(table, allChanges);
// after
List<TableChange> props = allChanges.stream()
    .filter(c -> c instanceof TableChange.SetProperty || c instanceof TableChange.RemoveProperty)
    .collect(Collectors.toList());
Spark3Util.applyPropertyChanges(table, props);

boolean isPropertyChange(TableChange c) {
  return c instanceof TableChange.SetProperty || c instanceof TableChange.RemoveProperty;
}
// filter list before calling
changes.stream().filter(this::isPropertyChange).collect(Collectors.toList());

static boolean isPropertyChange(TableChange c) {
  return c instanceof TableChange.SetProperty || c instanceof TableChange.RemoveProperty;
}

try {
  Spark3Util.applyPropertyChanges(table, changes);
} catch (UnsupportedOperationException e) {
  // log the unsupported change type and route it to a supported path
}

When it happens

Trigger: Calling Spark3Util.applyPropertyChanges with a TableChange instance other than TableChange.SetProperty or TableChange.RemoveProperty, e.g. a column-level change misrouted into the property path.

Common situations: Custom catalog/extension code building TableChange lists manually; framework versions where new TableChange subtypes were added upstream but this conversion path was not updated.

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: ${change}
• Cannot apply unknown table change:
• SparkCachedTableCatalog does not support altering tables
• SparkCachedTableCatalog does not support dropping tables
• SparkCachedTableCatalog does not support purging tables

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