apache/seatunnel · critical · IllegalStateException

Read snapshot for split ${split} fail

Error message

Read snapshot for split ${split} fail

What it means

MySqlSnapshotFetchTask.execute() runs a snapshot split read (MySqlSnapshotSplitReadTask) and then checks whether the result is completed or skipped. If the snapshot read finished without a completed/skipped result, the task throws IllegalStateException meaning the split was not fully read. This usually indicates the underlying JDBC snapshot query failed or was interrupted before emitting a completion signal.

Source

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

        snapshotSplitReadTask =
                new MySqlSnapshotSplitReadTask(
                        sourceFetchContext.getDbzConnectorConfig(),
                        sourceFetchContext.getOffsetContext(),
                        sourceFetchContext.getSnapshotChangeEventSourceMetrics(),
                        sourceFetchContext.getDatabaseSchema(),
                        sourceFetchContext.getConnection(),
                        sourceFetchContext.getDispatcher(),
                        split);
        SnapshotSplitChangeEventSourceContext changeEventSourceContext =
                new SnapshotSplitChangeEventSourceContext();
        SnapshotResult<MySqlOffsetContext> 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 (!sourceFetchContext.isExactlyOnce()) {
            taskRunning = false;
            if (changed) {
                log.debug("Skip merge changelog(exactly-once) for snapshot split {}", split);
            }
            return;
        }

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

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the preceding logs for the root cause (SQL exception, connection loss) in MySqlSnapshotSplitReadTask.createDataEventsForTable
2. Re-run the job; snapshot splits are retriable from the last checkpoint
3. Increase JDBC connection/socket timeouts and stabilize the network between SeaTunnel and MySQL
4. Reduce snapshot split size so each chunk query completes faster

Example fix

// before
throw new IllegalStateException(String.format("Read snapshot for split %s fail", split));
// after
// keep the error but surface the underlying cause:
throw new IllegalStateException(String.format("Read snapshot for split %s fail, last error: %s", split, snapshotResult.getError().orElse(null)));

// Job-level: rely on SeaTunnel checkpoint restart; wrap submission with retry
try {
    seatunnelClient.submitJob(jobConfig);
} catch (Exception e) {
    // retry with backoff; snapshot splits resume from checkpoint
}

When it happens

Trigger: Calling execute() on a snapshot split when snapshotResult.isCompletedOrSkipped() returns false, i.e. the snapshot read for that split ended abnormally (query error, cancelled read, missing completion marker).

Common situations: MySQL connection dropped mid-snapshot; query timeout on a large chunk; binlog/session killed by DBA or connection pool; schema changed while snapshot was running so the read task aborted.

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

• Read snapshot for split %s fail
• Cannot read the binlog filename and position via '<showMaste
• Interrupted while emitting initial DROP TABLE events
• User does not have the 'LOCK TABLES' privilege required to o
• User does not have the 'LOCK TABLES' privilege required to o

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