apache/iceberg · error · UnsupportedOperationException

Operation updateProperties is not supported after the table

Error message

Operation updateProperties is not supported after the table is serialized

What it means

SerializableTable guard: updateProperties() is refused on a deserialized table copy because the handle is read-only on executors. Property updates must be issued against the original catalog-loaded Table in the driver process.

Source

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

  @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
  public UpdateLocation updateLocation() {
    throw new UnsupportedOperationException(errorMsg("updateLocation"));
  }

  @Override
  public AppendFiles newAppend() {
    throw new UnsupportedOperationException(errorMsg("newAppend"));
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

Apply property updates on the driver using the live catalog table
Pass the Catalog plus table identifier to the code that needs updates
Use SerializableTable strictly for read-only access

Example fix

// before
serializableTable.updateProperties().set("write.format.default", "parquet").commit();
// after
catalog.loadTable(id).updateProperties().set("write.format.default", "parquet").commit();

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean canWrite = !(table instanceof SerializableTable);

Try / catch

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

Prevention

Apply property changes on the driver
Restrict SerializableTable to read paths
Review utility code for Table mutation on serialized handles

When it happens

Trigger: Calling updateProperties() on a SerializableTable, commonly in executor-side code or utility functions that mutate table properties.

Common situations: Generic maintenance utilities that set table properties; applying config changes inside distributed tasks.

Related errors

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