apache/iceberg · error · UnsupportedOperationException

Operation replaceSortOrder is not supported after the table

Error message

Operation replaceSortOrder is not supported after the table is serialized

What it means

SerializableTable guard: replaceSortOrder() is a metadata mutation, and deserialized table handles on executors only support reads. The error names the operation so callers know to perform sort-order replacement on the driver-side Table instance.

Source

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

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

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

Run sort order replacement on the driver with a live table from the catalog
Serialize only data-scanning work; keep all writes on the driver
Use catalog.loadTable(identifier) wherever SortOrder updates are required

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean canWrite = !(table instanceof SerializableTable);

Try / catch

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

Prevention

Run sort order maintenance on the driver
Keep all metadata writes off serialized table instances

When it happens

Trigger: Calling replaceSortOrder() on a SerializableTable instance, typically from distributed or wrapped table contexts.

Common situations: Maintenance jobs re-sorting tables using a table handle that was serialized and shipped to workers.

Related errors

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