apache/iceberg · warning · UnsupportedOperationException

Incremental scan is not supported

Error message

Incremental scan is not supported

What it means

The deprecated default TableScan.appendsBetween(long, long) throws UnsupportedOperationException because incremental append scans are not implemented by every TableScan implementation. It is scheduled for removal in 2.0.0 in favor of Table.newIncrementalAppendScan(); the throwing default documents that this scan implementation cannot do incremental scans.

Source

Thrown at api/src/main/java/org/apache/iceberg/TableScan.java:77

   * @throws IllegalArgumentException if the snapshot cannot be found or time travel is attempted on
   *     a tag
   */
  TableScan asOfTime(long timestampMillis);

  /**
   * Create a new {@link TableScan} to read appended data from {@code fromSnapshotId} exclusive to
   * {@code toSnapshotId} inclusive.
   *
   * @param fromSnapshotId the last snapshot id read by the user, exclusive
   * @param toSnapshotId read append data up to this snapshot id
   * @return a table scan which can read append data from {@code fromSnapshotId} exclusive and up to
   *     {@code toSnapshotId} inclusive
   * @deprecated since 1.0.0, will be removed in 2.0.0; use {@link Table#newIncrementalAppendScan()}
   *     instead.
   */
  @Deprecated
  default TableScan appendsBetween(long fromSnapshotId, long toSnapshotId) {
    throw new UnsupportedOperationException("Incremental scan is not supported");
  }

  /**
   * Create a new {@link TableScan} to read appended data from {@code fromSnapshotId} exclusive to
   * the current snapshot inclusive.
   *
   * @param fromSnapshotId - the last snapshot id read by the user, exclusive
   * @return a table scan which can read append data from {@code fromSnapshotId} exclusive and up to
   *     current snapshot inclusive
   * @deprecated since 1.0.0, will be removed in 2.0.0; use {@link Table#newIncrementalAppendScan()}
   *     instead.
   */
  @Deprecated
  default TableScan appendsAfter(long fromSnapshotId) {
    throw new UnsupportedOperationException("Incremental scan is not supported");
  }

  /**

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Migrate to table.newIncrementalAppendScan().appendsBetween(fromSnapshotId, toSnapshotId) as the deprecation instructs.
2. Use the current API: IncrementalAppendScan obtained from the Table, which all modern tables support.
3. Catch UnsupportedOperationException during the migration window if some scans cannot do incremental reads.
4. Remove reliance on the deprecated method before upgrading to Iceberg 2.0.0.

Example fix

// before
TableScan scan = table.newScan().appendsBetween(fromId, toId);

// after
TableScan scan =
    ((IncrementalAppendScan) table.newIncrementalAppendScan())
        .appendsBetween(fromId, toId);

// use the non-deprecated API path
org.apache.iceberg.IncrementalAppendScan incr =
    (org.apache.iceberg.IncrementalAppendScan) table.newIncrementalAppendScan();
TableScan scan = (TableScan) incr.appendsBetween(fromId, toId);

TableScan incrementalBetween(Table t, long fromId, long toId) {
  return (TableScan) ((org.apache.iceberg.IncrementalAppendScan) t.newIncrementalAppendScan())
      .appendsBetween(fromId, toId);
}

TableScan scan;
try {
  scan = table.newScan().appendsBetween(fromId, toId);
} catch (UnsupportedOperationException e) {
  scan = (TableScan) ((org.apache.iceberg.IncrementalAppendScan)
      table.newIncrementalAppendScan()).appendsBetween(fromId, toId);
}

When it happens

Trigger: Calling scan.appendsBetween(fromSnapshotId, toSnapshotId) — e.g. from snapshotToDataFiles-style incremental replication logic — on a TableScan implementation that does not override appendsBetween.

Common situations: Incremental ingest/replication pipelines written before 1.0.0 still using the deprecated API; running incremental scans against non-standard TableScan implementations or metadata tables.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• this.getClass().getName() + " doesn't implement removedDelet
• Cannot incrementally scan table of type %s
• Incremental scan is not supported
• Cannot scan table as of time %s: configured for incremental
• Cannot scan table using ref %s: configured for incremental d

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