apache/iceberg · error · UnsupportedOperationException

Operation newAppend is not supported after the table is…

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.

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.

Appendix: 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)