apache/iceberg · error · UnsupportedOperationException

doesn't implement toSnapshot

Error message

%s doesn't implement toSnapshot

What it means

Default-interface guard on IncrementalScan: thrown only when the concrete scan implementation did not override toSnapshot, so bounding the scan by an end snapshot is unsupported for that class. The %s names the offending runtime class; the cause is a missing implementation, not invalid arguments.

Solutions

1. Use a scan implementation that supports incremental scans and honors end-snapshot bounds
2. Catch UnsupportedOperationException and fall back to scanning the current snapshot
3. Override toSnapshot in the custom scan implementation

When it happens

Trigger: Thrown at api/src/main/java/org/apache/iceberg/IncrementalScan.java:99 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/1c9a5a3fbc4d9087. Report an issue: GitHub.

Appendix: source

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

   * <p>If the end snapshot is not configured, it defaults to the current table snapshot
   * (inclusive).
   *
   * @param toSnapshotId the end snapshot ID (inclusive)
   * @return this for method chaining
   */
  ThisT toSnapshot(long toSnapshotId);

  /**
   * Instructs this scan to look for changes up to a particular snapshot ref (inclusive).
   *
   * <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)