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 snapshot refs.

What it means

SideInputTable.refs() throws UnsupportedOperationException because branch/tag snapshot references are not part of the serialized metadata shipped into the side input. Resolving refs requires live catalog metadata.

Solutions

Resolve the ref (branch/tag) at pipeline construction time from the catalog, then build the side input from that snapshot.
Load the real table from the catalog if refs must be queried.
Guard refs-related calls with an instanceof SideInputTable check.

Example fix

// before
Map<String, SnapshotRef> refs = sideInputTable.refs();

// after
Map<String, SnapshotRef> refs = catalog.loadTable(identifier).refs();

Defensive patterns

Strategy: type-guard

Type guard

boolean supportsRefs = !(table instanceof SideInputTable);

Try / catch

try {
  Map<String, SnapshotRef> refs = table.refs();
} catch (UnsupportedOperationException e) {
  if (!e.getMessage().contains("snapshot refs")) throw e;
  // resolve refs from catalog table
}

Prevention

Resolve branches/tags to concrete snapshot IDs at pipeline construction time.
Avoid branch-ref lookups inside Beam workers.
Centralize ref resolution in catalog-accessing code.

When it happens

Trigger: Calling table.refs() on a SideInputTable, e.g. code that resolves which branch or tag to read from at runtime in a worker.

Common situations: Branch-aware read logic executing inside a DoFn; utilities that enumerate refs for validation.

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/6bc685a4766a37b4. Report an issue: GitHub.

Appendix: source

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

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

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

  @Override
  public List<HistoryEntry> history() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support snapshots.");
  }

  @Override
  public Map<String, SnapshotRef> refs() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support snapshot refs.");
  }

  @Override
  public List<StatisticsFile> statisticsFiles() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support statisticsFiles.");
  }

  @Override
  public List<PartitionStatisticsFile> partitionStatisticsFiles() {
    throw new UnsupportedOperationException(
        "SideInputTable is a read-only metadata adapter and does not support partitionStatisticsFiles.");
  }

  @Override
  public TableScan newScan() {
    throw new UnsupportedOperationException(

View on GitHub (pinned to 12126d8942)