apache/iceberg · error · UnsupportedOperationException

does not support altering tables

Error message

 does not support altering tables

What it means

SparkRewriteTableCatalog.alterTable(ident, changes) always throws UnsupportedOperationException because schema/partition/property changes must be applied through a real catalog; the rewrite catalog is read-only over cached table instances.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkRewriteTableCatalog.java:82

  @Override
  public SparkTable loadTable(Identifier ident, long timestampMicros) throws NoSuchTableException {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support time travel");
  }

  @Override
  public void invalidateTable(Identifier ident) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support table invalidation");
  }

  @Override
  public SparkTable createTable(Identifier ident, TableInfo tableInfo)
      throws TableAlreadyExistsException {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support creating tables");
  }

  @Override
  public SparkTable alterTable(Identifier ident, TableChange... changes) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support altering tables");
  }

  @Override
  public boolean dropTable(Identifier ident) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support dropping tables");
  }

  @Override
  public boolean purgeTable(Identifier ident) throws UnsupportedOperationException {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support purging tables");
  }

  @Override
  public void renameTable(Identifier oldIdent, Identifier newIdent) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support renaming tables");
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Apply table changes through the real catalog (SparkCatalog.alterTable) or SQL ALTER TABLE on the source catalog.
  2. Use Iceberg's UpdateSchema/UpdateProperties APIs on the loaded org.apache.iceberg.Table for programmatic changes.
  3. Never route DDL through SparkRewriteTableCatalog.

Example fix

// before
rewriteCatalog.alterTable(ident, TableChange.addColumn("new_col", IntegerType));
// after
sparkCatalog.alterTable(ident, TableChange.addColumn("new_col", IntegerType)); // DDL via the real catalog
Defensive patterns

Strategy: validation

Validate before calling

if (catalog instanceof SparkRewriteTableCatalog) {
  throw new IllegalArgumentException("ALTER TABLE must target a real Iceberg catalog");
}

Type guard

boolean supportsAlter(CatalogPlugin c) {
  return !(c instanceof SparkRewriteTableCatalog);
}

Try / catch

try {
  catalog.alterTable(ident, changes);
} catch (UnsupportedOperationException e) {
  realCatalog.alterTable(ident, changes);
}

Prevention

When it happens

Trigger: Calling alterTable with TableChange arguments on SparkRewriteTableCatalog, or generic clients applying DDL (ALTER TABLE) where the session resolves to the rewrite catalog.

Common situations: Migration scripts applying schema changes across catalogs; setting the rewrite catalog as session default so ALTER TABLE routes to it; framework code updating table properties generically.

Related errors

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