apache/iceberg · error · UnsupportedOperationException

doesn't implement useBranch

Error message

%s doesn't implement useBranch

What it means

Default-interface guard on IncrementalScan: thrown only when the concrete scan implementation did not override useBranch, so directing the scan at a named branch is unsupported for that class. The %s names the offending runtime class; it indicates the implementation lacks branch support, not that the branch name is bad.

Solutions

1. Use a scan implementation that supports branch selection
2. Resolve the branch to a snapshot ID first and configure the scan by snapshot instead
3. Override useBranch in the custom scan implementation

When it happens

Trigger: Thrown at api/src/main/java/org/apache/iceberg/IncrementalScan.java:110 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/8f2e1e5bdf0b5578. Report an issue: GitHub.

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/IncrementalScan.java:110

   * <p>If the end snapshot is not configured, it defaults to the current table snapshot
   * (inclusive).
   *
   * @param ref the end snapshot Ref (inclusive)
   * @return this for method chaining
   */
  default ThisT toSnapshot(String ref) {
    throw new UnsupportedOperationException(
        this.getClass().getName() + " doesn't implement toSnapshot");
  }

  /**
   * Use the specified branch
   *
   * @param branch the branch name
   * @return this for method chaining
   */
  default ThisT useBranch(String branch) {
    throw new UnsupportedOperationException(
        this.getClass().getName() + " doesn't implement useBranch");
  }
}

View on GitHub (pinned to 86d9c8fc54)