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 refresh.

What it means

SideInputTable is a lightweight, read-only adapter carrying serialized Iceberg table metadata into a Beam side input. It intentionally does not contact a catalog or file system, so refresh() is unsupported and throws UnsupportedOperationException. Refreshing is only meaningful on a live table backed by a catalog.

Solutions

  1. Remove the refresh() call when working with SideInputTable; metadata is fixed at pipeline construction time.
  2. If fresh metadata is needed, re-load the table from the catalog outside the pipeline (or in setup) and rebuild the side input.
  3. Guard with instanceof SideInputTable before calling mutation/lifecycle methods.

Example fix

// before
table.refresh();

// after
if (!(table instanceof SideInputTable)) {
  table.refresh();
}
Defensive patterns

Strategy: type-guard

Type guard

boolean supportsRefresh = !(table instanceof SideInputTable);

Try / catch

try {
  table.refresh();
} catch (UnsupportedOperationException e) {
  if (!e.getMessage().contains("does not support refresh")) throw e;
  // no-op: side input metadata is fixed
}

Prevention

When it happens

Trigger: Calling table.refresh() on a SideInputTable instance inside a DoFn or transform where the table was deserialized from a SerializableTableSpec.

Common situations: Generic code written against the Iceberg Table interface that calls refresh() unconditionally; moving code that worked with catalog-loaded tables to side-input tables; combining Beam Iceberg IO with custom scanning logic.

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/0a1cee99b3b450f9. Report an issue: GitHub.

Appendix: source

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

  @Override
  public LocationProvider locationProvider() {
    return locationProvider;
  }

  @Override
  public FileIO io() {
    return spec.getFileIO();
  }

  @Override
  public EncryptionManager encryption() {
    return encryptionManager;
  }

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

  @Override
  public Snapshot currentSnapshot() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support snapshots.");
  }

  @Override
  public Snapshot snapshot(long snapshotId) {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support snapshots.");
  }

  @Override
  public Iterable<Snapshot> snapshots() {
    throw new UnsupportedOperationException(

View on GitHub (pinned to 12126d8942)