{"record":{"id":"5f0784772ad808a2","repo":"apache/iceberg","slug":"using-a-reference-is-not-supported","errorCode":null,"errorMessage":"Using a reference is not supported","messagePattern":"Using a reference is not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/TableScan.java","lineNumber":49,"sourceCode":"   * Create a new {@link TableScan} from this scan's configuration that will use the given snapshot\n   * by ID.\n   *\n   * @param snapshotId a snapshot ID\n   * @return a new scan based on this with the given snapshot ID\n   * @throws IllegalArgumentException if the snapshot cannot be found\n   */\n  TableScan useSnapshot(long snapshotId);\n\n  /**\n   * Create a new {@link TableScan} from this scan's configuration that will use the given\n   * reference.\n   *\n   * @param ref reference\n   * @return a new scan based on the given reference.\n   * @throws IllegalArgumentException if a reference with the given name could not be found\n   */\n  default TableScan useRef(String ref) {\n    throw new UnsupportedOperationException(\"Using a reference is not supported\");\n  }\n\n  /**\n   * Create a new {@link TableScan} from this scan's configuration that will use the most recent\n   * snapshot as of the given time in milliseconds on the branch in the scan or main if no branch is\n   * set.\n   *\n   * @param timestampMillis a timestamp in milliseconds.\n   * @return a new scan based on this with the current snapshot at the given time\n   * @throws IllegalArgumentException if the snapshot cannot be found or time travel is attempted on\n   *     a tag\n   */\n  TableScan asOfTime(long timestampMillis);\n\n  /**\n   * Create a new {@link TableScan} to read appended data from {@code fromSnapshotId} exclusive to\n   * {@code toSnapshotId} inclusive.\n   *","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/TableScan.java#L31-L67","documentation":"The default TableScan.useRef(String) throws UnsupportedOperationException because a TableScan implementation may not support snapshot references (branches/tags). Implementations such as DataTableScan override it; other TableScan implementations (metadata-table scans, custom scans) keep the throwing default.","triggerScenarios":"Calling scan.useRef(\"branch-name\") (directly, or via helpers like planTasks/canDeleteUsingMetadata/dataFiles that refine scans with a reference) on a TableScan implementation that doesn't override useRef.","commonSituations":"Running Spark/Merge-on-read delete planning against metadata tables or custom scans; applying branch/tag-based reads to scan objects obtained from non-standard scan implementations; copy-on-write utilities selecting a snapshot by reference name.","solutions":["Obtain the TableScan from table.newScan() on a real data table (DataTableScan supports useRef).","Instead of useRef, select the snapshot explicitly via useSnapshotId(snapshotId) resolved through table.snapshot(ref) or table.refs().get(ref).","Catch UnsupportedOperationException and fall back to snapshot-ID-based refinement.","Override useRef in custom TableScan implementations."],"exampleFix":"// before\nTableScan scan = table.newScan().useRef(\"audit-branch\");\n\n// after\nSnapshot snap = table.snapshot(\"audit-branch\");\nTableScan scan = (snap != null)\n    ? table.newScan().useSnapshotId(snap.snapshotId())\n    : table.newScan();","handlingStrategy":"validation","validationCode":"Snapshot ref = table.snapshot(\"audit-branch\");\nif (ref == null) {\n  throw new IllegalArgumentException(\"Reference not found: audit-branch\");\n}\nTableScan scan = table.newScan().useSnapshotId(ref.snapshotId());","typeGuard":"TableScan safeUseRef(Table t, String ref) {\n  Snapshot s = t.snapshot(ref);\n  return (s != null) ? t.newScan().useSnapshotId(s.snapshotId()) : t.newScan();\n}","tryCatchPattern":"try {\n  scan = table.newScan().useRef(ref);\n} catch (UnsupportedOperationException e) {\n  Snapshot s = table.snapshot(ref);\n  scan = (s != null) ? table.newScan().useSnapshotId(s.snapshotId()) : table.newScan();\n}","preventionTips":["Prefer resolving the reference to a snapshot ID via table.snapshot(ref) — this works on all scans","Only use useRef on scans from real data tables (DataTableScan)","Validate the reference exists in table.refs() before refining the scan"],"tags":["unsupported-operation","branches","table-scan"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}