apache/iceberg · error · UnsupportedOperationException

Operation newAppend is not supported after the table is seri

Error message

Operation newAppend is not supported after the table is serialized

What it means

SerializableTable represents a Table that has been serialized for use in a distributed task (Spark/Flink executors). It carries table metadata for reads and scans only; it has no catalog connection and cannot commit snapshots. newAppend() is therefore deliberately unsupported and throws UnsupportedOperationException to prevent silent, lost writes.

Source

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

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

  @Override
  public OverwriteFiles newOverwrite() {
    throw new UnsupportedOperationException(errorMsg("newOverwrite"));
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

Load the table fresh from the catalog where the append should commit: catalog.loadTable(identifier).newAppend()...commit()
Run the append on the driver/catalog-connected context, not inside the distributed task holding the serialized table
Use the framework's built-in writer (e.g. iceberg-spark's writes) instead of manually appending from executor code
Guard against misuse with an instanceof SerializableTable check before creating write operations

Example fix

// before
Table table = serializedTable; // SerializableTable on executor
table.newAppend().appendFile(df).commit();
// after
// on the driver, with a catalog connection:
Table table = catalog.loadTable(identifier);
table.newAppend().appendFile(df).commit();

Defensive patterns

Strategy: try-catch

Validate before calling

if (table instanceof org.apache.iceberg.SerializableTable) {
  throw new IllegalStateException("newAppend() requires a catalog-backed Table");
}

Type guard

boolean canCommit = !(table instanceof org.apache.iceberg.SerializableTable);

Try / catch

try {
  table.newAppend().appendFile(f).commit();
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("not supported after the table is serialized")) {
    catalog.loadTable(identifier).newAppend().appendFile(f).commit();
  } else { throw e; }
}

Prevention

Perform appends on the driver or wherever a live Catalog/Table is available
Ship data files, not the Table object, across task boundaries
Prefer engine-native sinks (Spark/Flink writers) over manual appends in executors
Type-check tables with instanceof SerializableTable in generic utilities

When it happens

Trigger: Calling table.newAppend() on a deserialized SerializableTable inside a worker task (e.g. inside a mapPartitions/MapFunction that received a serialized table).

Common situations: Writing data in a Spark/Flink job by obtaining a Table from a serialized reference; custom writers created from SerializableTable instead of a catalog-loaded table; moving code from driver-side (where newAppend works) into executor code.

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

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