apache/beam · error · java.lang.UnsupportedOperationException

SideInputTable is a read-only metadata adapter and does not…

Error message

SideInputTable is a read-only metadata adapter and does not support table mutations.

What it means

SideInputTable.updateSchema() throws UnsupportedOperationException because the adapter is read-only and does not support table mutations. Schema evolution must be performed on the real catalog-backed Table, not on the side-input metadata wrapper.

Solutions

Reload the table from the catalog (catalog.loadTable(id)) and call updateSchema() on that instance, then commit().
Keep a separate writable Table reference for mutation paths; restrict SideInputTable usage to read-only metadata.
Fail fast in code that receives a Table by checking for SideInputTable before mutation.

Example fix

// before
sideInputTable.updateSchema().addColumn("new_col", Types.LongType.get()).commit();
// after
org.apache.iceberg.Table table = catalog.loadTable(tableIdentifier);
table.updateSchema().addColumn("new_col", Types.LongType.get()).commit();

Defensive patterns

Strategy: type-guard

Validate before calling

if (table instanceof org.apache.beam.sdk.io.iceberg.SideInputTable) {
  throw new IllegalArgumentException("Schema updates require a catalog-loaded Table");
}

Type guard

boolean isMutable(org.apache.iceberg.Table t) {
  return !(t instanceof org.apache.beam.sdk.io.iceberg.SideInputTable);
}

Try / catch

try {
  table.updateSchema().addColumn("c", Types.LongType.get()).commit();
} catch (UnsupportedOperationException e) {
  catalog.loadTable(tableIdentifier).updateSchema()
      .addColumn("c", Types.LongType.get()).commit();
}

Prevention

Centralize schema evolution behind a helper that always reloads the table from the catalog
Type mutation-utility parameters narrowly or assert non-SideInputTable at entry
Never cache a SideInputTable for later writes

When it happens

Trigger: Calling updateSchema() (e.g. to add/rename columns) on a SideInputTable instance.

Common situations: Shared write helpers that accept org.apache.iceberg.Table and attempt schema updates; confusion between a table's metadata view (side input) and its writable catalog handle.

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/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/10213affc566a1ea. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/SideInputTable.java:243

    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support scans directly.");
  }

  @Override
  public IncrementalAppendScan newIncrementalAppendScan() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support scans directly.");
  }

  @Override
  public IncrementalChangelogScan newIncrementalChangelogScan() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support scans directly.");
  }

  @Override
  public UpdateSchema updateSchema() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support table mutations.");
  }

  @Override
  public UpdatePartitionSpec updateSpec() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support table mutations.");
  }

  @Override
  public UpdateProperties updateProperties() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support table mutations.");
  }

  @Override
  public ReplaceSortOrder replaceSortOrder() {
    throw new UnsupportedOperationException(

View on GitHub (pinned to 12126d8942)