What causes "Incremental scan is not supported" in apache/iceberg?

Use the table's standard scan (table.newScan(), i.e. DataTableScan) which supports appendsBetween/appendsAfter

apache/iceberg · error · UnsupportedOperationException

Incremental scan is not supported

Error message

Incremental scan is not supported

What it means

BaseTableScan is the legacy pre-v1 TableScan implementation that only supports full snapshot scans. appendsBetween (incremental scan between two snapshot IDs) is intentionally unimplemented and always throws UnsupportedOperationException; use the modern TableScan implementations (DataTableScan) instead.

Source

Thrown at core/src/main/java/org/apache/iceberg/BaseTableScan.java:34

 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.iceberg;

import org.apache.iceberg.io.CloseableIterable;
import org.apache.iceberg.util.TableScanUtil;

/** Base class for {@link TableScan} implementations. */
abstract class BaseTableScan extends SnapshotScan<TableScan, FileScanTask, CombinedScanTask>
    implements TableScan {

  protected BaseTableScan(Table table, Schema schema, TableScanContext context) {
    super(table, schema, context);
  }

  @Override
  public TableScan appendsBetween(long fromSnapshotId, long toSnapshotId) {
    throw new UnsupportedOperationException("Incremental scan is not supported");
  }

  @Override
  public TableScan appendsAfter(long fromSnapshotId) {
    throw new UnsupportedOperationException("Incremental scan is not supported");
  }

  @Override
  public CloseableIterable<CombinedScanTask> planTasks() {
    CloseableIterable<FileScanTask> fileScanTasks = planFiles();
    CloseableIterable<FileScanTask> splitFiles =
        TableScanUtil.splitFiles(fileScanTasks, targetSplitSize());
    return TableScanUtil.planTasks(
        splitFiles, targetSplitSize(), splitLookback(), splitOpenFileCost());
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use the table's standard scan (table.newScan(), i.e. DataTableScan) which supports appendsBetween/appendsAfter
Ensure the catalog returns DataTableScan/KeyedTableScan rather than the legacy BaseTableScan
Replace incremental logic with explicit snapshot-difference reading (compare manifests between snapshots) if incremental scan isn't available
Upgrade Iceberg — BaseTableScan-based paths were superseded by the v1.1+ TableScan implementations

Example fix

// before
TableScan scan = new BaseTableScan(table, schema, context);
scan.appendsBetween(fromId, toId);
// after
TableScan scan = table.newScan();
CloseableIterable<ScanTask> tasks = scan.appendsBetween(fromId, toId).planTasks();

Defensive patterns

Strategy: fallback

Validate before calling

TableScan scan = table.newScan();
if (scan.getClass().getSimpleName().equals("BaseTableScan")) {
  throw new IllegalStateException("legacy scan lacks incremental support");
}

Try / catch

try { return scan.appendsBetween(from, to); } catch (UnsupportedOperationException e) { return fullScanFallback(); }

Prevention

Always create scans via table.newScan()
Ensure custom catalogs return DataTableScan
Prefer engine-native Iceberg sources for incremental/streaming reads

When it happens

Trigger: Calling scan.appendsBetween(fromId, toId) on a table whose scan class resolves to BaseTableScan — i.e. legacy code paths or tables/providers that don't produce incremental-capable scans.

Common situations: Custom catalogs returning BaseTableScan; very old Iceberg migrations; code using the deprecated TableScan API against a scan implementation lacking incremental support; streaming readers pointed at unsupported scan types.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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