apache/iceberg · error · IllegalArgumentException

Unknown starting strategy:

Error message

Unknown starting strategy: 

What it means

ContinuousSplitPlannerImpl.startSnapshot switches over the StreamingStartingStrategy and has no handling for the given strategy, throwing IllegalArgumentException. The strategy value is un recognized by this connector version.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/ContinuousSplitPlannerImpl.java:244

      case INCREMENTAL_FROM_LATEST_SNAPSHOT_EXCLUSIVE:
        return Optional.ofNullable(table.currentSnapshot());
      case INCREMENTAL_FROM_EARLIEST_SNAPSHOT:
        return Optional.ofNullable(SnapshotUtil.oldestAncestor(table));
      case INCREMENTAL_FROM_SNAPSHOT_ID:
        Snapshot matchedSnapshotById = table.snapshot(scanContext.startSnapshotId());
        Preconditions.checkArgument(
            matchedSnapshotById != null,
            "Start snapshot id not found in history: " + scanContext.startSnapshotId());
        return Optional.of(matchedSnapshotById);
      case INCREMENTAL_FROM_SNAPSHOT_TIMESTAMP:
        Snapshot matchedSnapshotByTimestamp =
            SnapshotUtil.oldestAncestorAfter(table, scanContext.startSnapshotTimestamp());
        Preconditions.checkArgument(
            matchedSnapshotByTimestamp != null,
            "Cannot find a snapshot after: " + scanContext.startSnapshotTimestamp());
        return Optional.of(matchedSnapshotByTimestamp);
      default:
        throw new IllegalArgumentException(
            "Unknown starting strategy: " + scanContext.streamingStartingStrategy());
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the streaming-starting-strategy property value and set a valid one (e.g., INCREMENTAL_FROM_LATEST_SNAPSHOT).
2. Restore checkpoints/savepoints with the same connector version that produced them, or upgrade both together.
3. Upgrade the Iceberg Flink connector if the strategy was introduced in a newer version.

Example fix

// before
.env("streaming-starting-strategy", "INCREMENTAL_FROM_EARLIEST") // invalid
// after
.env("streaming-starting-strategy", "INCREMENTAL_FROM_LATEST_SNAPSHOT")

String strategy = table.properties().getOrDefault("streaming-starting-strategy", "TABLE_SCAN_THEN_INCREMENTAL");
java.util.Set<String> valid = java.util.Set.of("TABLE_SCAN_THEN_INCREMENTAL", "INCREMENTAL_FROM_SNAPSHOT_ID", "INCREMENTAL_FROM_SNAPSHOT_TIMESTAMP", "INCREMENTAL_FROM_LATEST_SNAPSHOT");
if (!valid.contains(strategy)) throw new IllegalArgumentException("Invalid streaming-starting-strategy: " + strategy);

When it happens

Trigger: Resuming a streaming scan whose saved state (IcebergEnumeratorPosition) or table property (streaming-starting-strategy) contains a strategy value not in the switch (TABLE_SCAN_THEN_INCREMENTAL, INCREMENTAL_FROM_SNAPSHOT_ID, INCREMENTAL_FROM_SNAPSHOT_TIMESTAMP, INCREMENTAL_FROM_LATEST_SNAPSHOT).

Common situations: Restoring a checkpoint/savepoint produced by a different connector version with a new strategy; manually setting an invalid streaming-starting-strategy property value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown starting strategy:
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}
• Failed to discover new splits
• Cannot apply unknown unique constraint:

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