apache/seatunnel · critical · IllegalStateException

Read snapshot for split %s fail

Error message

Read snapshot for split %s fail

What it means

Thrown by SqlServerSnapshotFetchTask.execute when the snapshot split read task finishes without reporting a completed or skipped result. It signals that the snapshot reader could not confirm it fully read the split's key range, so the fetch task aborts by throwing IllegalStateException to fail the reader rather than continue with unverified data.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/source/reader/fetch/scan/SqlServerSnapshotFetchTask.java:79

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

        SnapshotResult<SqlServerOffsetContext> 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. Check SQL Server connectivity and stability between worker and database during snapshot; fix network/timeout issues
2. Inspect preceding log lines from SqlServerSnapshotSplitReadTask for the underlying cause (query failure, cancelled snapshot)
3. Retry the job; if reproducible, reduce snapshot parallelism or chunk size to lower load per split
4. Upgrade the connector version — early versions had snapshot retry bugs

// Before submitting, confirm the table is snapshotable and connection is stable
try (Connection c = DriverManager.getConnection(url, user, pass)) {
    if (!c.isValid(10)) throw new IllegalStateException("SQL Server unreachable");
    try (Statement s = c.createStatement();
         ResultSet rs = s.executeQuery("SELECT COUNT(*) FROM " + table)) {
        rs.next();
        System.out.println("rows=" + rs.getLong(1));
    }
}

// Wrap job submission/restart in retry
try {
    submitJob(cfg);
} catch (Exception e) {
    if (e.getMessage() != null && e.getMessage().contains("Read snapshot for split")) {
        retryWithBackoff(() -> submitJob(cfg), 3);
    } else throw e;
}

When it happens

Trigger: snapshotSplitReadTask.execute() returns a SnapshotResult whose isCompletedOrSkipped() is false — e.g. the underlying Debezium snapshot read loop stopped early, was cancelled, or returned a failure result for the split instead of completing.

Common situations: SQL Server connection dropped mid-snapshot; CDC/snapshot process cancelled internally (e.g. stop-point reached incorrectly); Debezium connector task failed silently and returned an incomplete result; retry loop exhausted inside the split read task.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Could not find existing binlog information while attempting
• Snapshotting of table ${table.id()} failed
• Snapshot was interrupted before completion
• Invalid state: currentSplitId is null when emitting records.
• Cannot fetch from another split - no split remaining.

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