{"record":{"id":"10213affc566a1ea","repo":"apache/beam","slug":"sideinputtable-is-a-read-only-metadata-adapter-and-does-not-10213a","errorCode":null,"errorMessage":"SideInputTable is a read-only metadata adapter and does not support table mutations.","messagePattern":"SideInputTable is a read-only metadata adapter and does not support table mutations\\.","errorType":"exception","errorClass":"java.lang.UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/SideInputTable.java","lineNumber":243,"sourceCode":"    throw new UnsupportedOperationException(\n        \"SideInputTable is a read-only metadata adapter and does not support scans directly.\");\n  }\n\n  @Override\n  public IncrementalAppendScan newIncrementalAppendScan() {\n    throw new UnsupportedOperationException(\n        \"SideInputTable is a read-only metadata adapter and does not support scans directly.\");\n  }\n\n  @Override\n  public IncrementalChangelogScan newIncrementalChangelogScan() {\n    throw new UnsupportedOperationException(\n        \"SideInputTable is a read-only metadata adapter and does not support scans directly.\");\n  }\n\n  @Override\n  public UpdateSchema updateSchema() {\n    throw new UnsupportedOperationException(\n        \"SideInputTable is a read-only metadata adapter and does not support table mutations.\");\n  }\n\n  @Override\n  public UpdatePartitionSpec updateSpec() {\n    throw new UnsupportedOperationException(\n        \"SideInputTable is a read-only metadata adapter and does not support table mutations.\");\n  }\n\n  @Override\n  public UpdateProperties updateProperties() {\n    throw new UnsupportedOperationException(\n        \"SideInputTable is a read-only metadata adapter and does not support table mutations.\");\n  }\n\n  @Override\n  public ReplaceSortOrder replaceSortOrder() {\n    throw new UnsupportedOperationException(","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/SideInputTable.java#L225-L261","documentation":"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.","triggerScenarios":"Calling updateSchema() (e.g. to add/rename columns) on a SideInputTable instance.","commonSituations":"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.","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."],"exampleFix":"// before\nsideInputTable.updateSchema().addColumn(\"new_col\", Types.LongType.get()).commit();\n// after\norg.apache.iceberg.Table table = catalog.loadTable(tableIdentifier);\ntable.updateSchema().addColumn(\"new_col\", Types.LongType.get()).commit();","handlingStrategy":"type-guard","validationCode":"if (table instanceof org.apache.beam.sdk.io.iceberg.SideInputTable) {\n  throw new IllegalArgumentException(\"Schema updates require a catalog-loaded Table\");\n}","typeGuard":"boolean isMutable(org.apache.iceberg.Table t) {\n  return !(t instanceof org.apache.beam.sdk.io.iceberg.SideInputTable);\n}","tryCatchPattern":"try {\n  table.updateSchema().addColumn(\"c\", Types.LongType.get()).commit();\n} catch (UnsupportedOperationException e) {\n  catalog.loadTable(tableIdentifier).updateSchema()\n      .addColumn(\"c\", Types.LongType.get()).commit();\n}","preventionTips":["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"],"tags":["java","iceberg","unsupported-operation","schema-evolution"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}