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 scans directly.

What it means

SideInputTable.newScan() throws UnsupportedOperationException: the adapter does not support direct table scans. In Beam's Iceberg IO, reading is performed via the IO transforms using the pre-planned data files in the spec, not via Iceberg TableScan.

Solutions

  1. Use Beam's Iceberg IO read transforms instead of manual TableScan on side-input tables.
  2. Create the scan from a catalog-loaded Table, or convert scan results to a side input before the pipeline runs.
  3. Perform scan-based planning at pipeline construction time and ship results via SerializableTableSpec/SideInputTable.

Example fix

// before
CloseableIterable<Row> rows = sideInputTable.newScan().project(schema).planFiles()...;

// after
pipeline.apply(IcebergIO.readRows(catalogConfig, tableIdentifier));
Defensive patterns

Strategy: type-guard

Type guard

boolean supportsScans = !(table instanceof SideInputTable);

Try / catch

try {
  TableScan scan = table.newScan();
} catch (UnsupportedOperationException e) {
  if (!e.getMessage().contains("scans directly")) throw e;
  // use Beam Iceberg IO read transforms or a catalog-backed table
}

Prevention

When it happens

Trigger: Calling table.newScan() (or building a TableScan from it) on a SideInputTable inside a DoFn or custom read path.

Common situations: Custom read code that assumes any Iceberg Table can produce a TableScan; mixing direct Iceberg reads with Beam Iceberg IO side inputs.

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/8dd2288fd97c48ba. Report an issue: GitHub.

Appendix: source

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

    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(
        "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(

View on GitHub (pinned to 12126d8942)