{"record":{"id":"90415df5748b7712","repo":"apache/iceberg","slug":"cannot-select-ref-in-table-tabletype","errorCode":null,"errorMessage":"Cannot select ref in table: ${tableType}","messagePattern":"Cannot select ref in table: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/BaseAllMetadataTableScan.java","lineNumber":54,"sourceCode":"  private static final Logger LOG = LoggerFactory.getLogger(BaseAllMetadataTableScan.class);\n\n  BaseAllMetadataTableScan(Table table, Schema schema, MetadataTableType tableType) {\n    super(table, schema, tableType);\n  }\n\n  BaseAllMetadataTableScan(\n      Table table, Schema schema, MetadataTableType tableType, TableScanContext context) {\n    super(table, schema, tableType, context);\n  }\n\n  @Override\n  public TableScan useSnapshot(long scanSnapshotId) {\n    throw new UnsupportedOperationException(\"Cannot select snapshot in table: \" + tableType());\n  }\n\n  @Override\n  public TableScan useRef(String ref) {\n    throw new UnsupportedOperationException(\"Cannot select ref in table: \" + tableType());\n  }\n\n  @Override\n  public TableScan asOfTime(long timestampMillis) {\n    throw new UnsupportedOperationException(\"Cannot select snapshot in table: \" + tableType());\n  }\n\n  @Override\n  public CloseableIterable<FileScanTask> planFiles() {\n    String metadataTableName = table().name() + \".\" + tableType().name().toLowerCase(Locale.ROOT);\n    LOG.info(\n        \"Scanning metadata table {} with filter {}.\",\n        metadataTableName,\n        ExpressionUtil.toSanitizedString(filter()));\n    Listeners.notifyAll(new ScanEvent(metadataTableName, 0L, filter(), schema()));\n\n    return doPlanFiles();\n  }","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/BaseAllMetadataTableScan.java#L36-L72","documentation":"BaseAllMetadataTableScan.useRef() always throws UnsupportedOperationException: all_* metadata tables are defined across every snapshot/branch, so resolving a named branch or tag ref is not meaningful and is intentionally rejected.","triggerScenarios":"Calling tableScan.useRef(\"branch\") on a scan of an all_* metadata table such as all_manifests or all_delete_files.","commonSituations":"Queries like SELECT * FROM db.t.all_entries VERSION AS OF 'main' in Spark/Flink engines; shared scan-builder utilities applying ref selection unconditionally.","solutions":["Drop the useRef call for all_* metadata table scans","Use a per-snapshot metadata table (entries, files, delete_files) with useRef instead if you need ref-scoped results","Gate ref selection in engine planners on the table not being an all_* metadata table"],"exampleFix":"// before\nscan = table.scan(\"all_entries\").useRef(\"audit-branch\");\n// after\nscan = table.scan(\"entries\").useRef(\"audit-branch\"); // ref-scoped non-all metadata table\n","handlingStrategy":"validation","validationCode":"if (!metadataTableName.startsWith(\"all_\")) {\n  scan = scan.useRef(refName);\n}","typeGuard":"null","tryCatchPattern":"try { scan.useRef(ref); } catch (UnsupportedOperationException e) { /* all_* table: ref selection unsupported */ }","preventionTips":["Gate ref/time-travel APIs on table type in shared scan builders","Use per-snapshot metadata tables (entries/files) when ref scoping is needed","Document that all_* tables ignore branching"],"tags":["unsupported-operation","metadata-table","branching"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}