apache/seatunnel · error · java.lang.IllegalStateException

Read snapshot for split %s fail

Error message

Read snapshot for split %s fail

What it means

Db2SnapshotFetchTask.execute runs the snapshot split read task and requires the result to be completed or skipped. If the returned SnapshotResult is neither, the snapshot did not finish successfully, so the task marks itself not running and fails with this IllegalStateException naming the split.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-db2/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/db2/source/reader/fetch/scan/Db2SnapshotFetchTask.java:78

                new Db2SnapshotSplitReadTask(
                        sourceFetchContext.getDbzConnectorConfig(),
                        sourceFetchContext.getOffsetContext(),
                        sourceFetchContext.getSnapshotChangeEventSourceMetrics(),
                        sourceFetchContext.getDatabaseSchema(),
                        sourceFetchContext.getDataConnection(),
                        sourceFetchContext.getDispatcher(),
                        split);
        SnapshotSplitChangeEventSourceContext changeEventSourceContext =
                new SnapshotSplitChangeEventSourceContext();

        SnapshotResult<Db2OffsetContext> snapshotResult =
                snapshotSplitReadTask.execute(
                        changeEventSourceContext,
                        sourceFetchContext.getPartition(),
                        sourceFetchContext.getOffsetContext());
        if (!snapshotResult.isCompletedOrSkipped()) {
            taskRunning = false;
            throw new IllegalStateException(
                    String.format("Read snapshot for split %s fail", split));
        }

        boolean changed =
                changeEventSourceContext
                        .getHighWatermark()
                        .isAfter(changeEventSourceContext.getLowWatermark());
        if (!context.isExactlyOnce()) {
            taskRunning = false;
            if (changed) {
                log.debug("Skip merge changelog(exactly-once) for snapshot split {}", split);
            }
            return;
        }

        final IncrementalSplit backfillSplit = createBackFillLsnSplit(changeEventSourceContext);
        // optimization that skip the binlog read when the low watermark equals high
        // watermark

View on GitHub (pinned to cf67b549a7)

Solutions

1. Retry the job so the failed split is re-executed from its checkpointed position
2. Check DB2 server logs for lock waits, errors, or DDL during the snapshot window
3. Avoid schema changes (DDL) on tables while a snapshot is running
4. Increase checkpoint/timeout budgets if the snapshot is being cancelled prematurely

try { runPipeline(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Read snapshot for split")) { restartFromCheckpoint(); } }

When it happens

Trigger: SnapshotSplitReadTask.execute returns a SnapshotResult whose status is not COMPLETED or SKIPPED — e.g. the underlying snapshot read was cancelled, aborted due to schema change, or interrupted mid-split.

Common situations: Concurrent DDL on the snapshot table invalidating the read; checkpoint cancellation shutting down the change event source; DB2 connection loss aborting the snapshot query; job restart racing with split completion.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Snapshotting of table failed
• Read snapshot for split ${split} fail
• Snapshot was interrupted before completion
• Error to discover tables:
• Table is not enabled for capture

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/1a20d3247931365a. Report an issue: GitHub.