apache/seatunnel · error · IllegalStateException

Read snapshot for split

Error message

Read snapshot for split ${split} fail

What it means

PostgresSnapshotFetchTask.execute runs the snapshot split read task and expects a result that is completed or skipped. If the snapshot result is neither, the task marks itself not running and throws IllegalStateException 'Read snapshot for split <split> fail', meaning the snapshot chunk could not be read.

Solutions

1. Rerun the job (snapshot splits are retried/resumable via checkpoint state).
2. Reduce snapshot chunk size to make each chunk read shorter and more reliable.
3. Verify the snapshot user has SELECT on all captured tables and stable connectivity to the DB.
4. Check for concurrent DDL/truncations on the table during snapshot and reschedule them.
5. Inspect the underlying reader logs for the root failure of the chunk read.

// Pre-check SELECT privilege on all captured tables
SELECT has_table_privilege(current_user, 'public.orders', 'SELECT');

try {
    task.execute(ctx, partition, offsetContext);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Read snapshot for split")) {
        // retry the split or resubmit the job with smaller chunk size
    }
}

When it happens

Trigger: SnapshotSplitReadTask.execute returns an unfinished/incomplete result — typically because the snapshot query failed, the high/low watermark protocol broke, or the source was cancelled mid-chunk.

Common situations: Database connection dropped during a large snapshot chunk read; table too large causing chunk read timeouts; permission errors on the snapshotted table; concurrent DDL invalidating the chunk read.

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

• Cannot find table schema for table
• A slot marked as temporary or with an exported snapshot was…
• Cannot drop replication slot
• Cannot find table schema for table
• Cannot obtain valid replication slot

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/postgres/source/reader/snapshot/PostgresSnapshotFetchTask.java:71

        snapshotSplitReadTask =
                new PostgresSnapshotSplitReadTask(
                        sourceFetchContext.getDbzConnectorConfig(),
                        sourceFetchContext.getOffsetContext(),
                        sourceFetchContext.getSnapshotChangeEventSourceMetrics(),
                        sourceFetchContext.getDatabaseSchema(),
                        sourceFetchContext.getDataConnection(),
                        sourceFetchContext.getDispatcher(),
                        split);
        SnapshotSplitChangeEventSourceContext changeEventSourceContext =
                new SnapshotSplitChangeEventSourceContext();
        SnapshotResult 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 = createBackFillWalSplit(changeEventSourceContext);
        // optimization that skip the binlog read when the low watermark equals high
        // watermark
        // todo Add backfill task

View on GitHub (pinned to cf67b549a7)