apache/iceberg · error · UnsupportedOperationException

Operation updateSchema is not supported after the table is s

Error message

Operation updateSchema is not supported after the table is serialized

What it means

Schema evolution is a write operation requiring live TableOperations; SerializableTable only supports reads. updateSchema() throws UnsupportedOperationException with errorMsg("updateSchema") indicating the operation is unavailable after serialization.

Source

Thrown at core/src/main/java/org/apache/iceberg/SerializableTable.java:352

  @Override
  public Snapshot snapshot(long snapshotId) {
    return lazyTable().snapshot(snapshotId);
  }

  @Override
  public Iterable<Snapshot> snapshots() {
    return lazyTable().snapshots();
  }

  @Override
  public List<HistoryEntry> history() {
    return lazyTable().history();
  }

  @Override
  public UpdateSchema updateSchema() {
    throw new UnsupportedOperationException(errorMsg("updateSchema"));
  }

  @Override
  public UpdatePartitionSpec updateSpec() {
    throw new UnsupportedOperationException(errorMsg("updateSpec"));
  }

  @Override
  public UpdateProperties updateProperties() {
    throw new UnsupportedOperationException(errorMsg("updateProperties"));
  }

  @Override
  public ReplaceSortOrder replaceSortOrder() {
    throw new UnsupportedOperationException(errorMsg("replaceSortOrder"));
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

Pass the original catalog-loaded Table (or the Catalog itself) to code that performs schema updates
Perform schema updates on the driver with a live table
Check for the SerializableTable wrapper before attempting write operations

Example fix

// before
Table t = SerializableTable.of(table);
t.updateSchema().addColumn("x", Types.IntegerType.get()).commit();
// after
table.updateSchema().addColumn("x", Types.IntegerType.get()).commit();

Defensive patterns

Strategy: validation

Validate before calling

if (table instanceof SerializableTable) { throw new UnsupportedOperationException("Schema updates require a live catalog table"); }

Type guard

boolean canWrite = !(table instanceof SerializableTable);

Try / catch

try { table.updateSchema().commit(); } catch (UnsupportedOperationException e) { catalog.loadTable(id).updateSchema().commit(); }

Prevention

Perform all schema evolution on the driver with a live table
Pass Catalog + identifier, not serialized tables, to write paths
Document that SerializableTable is read-only

When it happens

Trigger: Calling updateSchema() on a Table reference that is actually a SerializableTable (e.g., inside an executor task or after SerializableTable.of()).

Common situations: Generic code that accepts a Table and tries to evolve the schema; passing serialized tables into frameworks that perform schema updates.

Related errors

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