{"record":{"id":"64110b35f38c502b","repo":"apache/seatunnel","slug":"read-snapshot-for-split-split-fail","errorCode":null,"errorMessage":"Read snapshot for split ${split} fail","messagePattern":"Read snapshot for split (.+?) fail","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/source/reader/fetch/scan/MySqlSnapshotFetchTask.java","lineNumber":78,"sourceCode":"        snapshotSplitReadTask =\n                new MySqlSnapshotSplitReadTask(\n                        sourceFetchContext.getDbzConnectorConfig(),\n                        sourceFetchContext.getOffsetContext(),\n                        sourceFetchContext.getSnapshotChangeEventSourceMetrics(),\n                        sourceFetchContext.getDatabaseSchema(),\n                        sourceFetchContext.getConnection(),\n                        sourceFetchContext.getDispatcher(),\n                        split);\n        SnapshotSplitChangeEventSourceContext changeEventSourceContext =\n                new SnapshotSplitChangeEventSourceContext();\n        SnapshotResult<MySqlOffsetContext> snapshotResult =\n                snapshotSplitReadTask.execute(\n                        changeEventSourceContext,\n                        sourceFetchContext.getPartition(),\n                        sourceFetchContext.getOffsetContext());\n        if (!snapshotResult.isCompletedOrSkipped()) {\n            taskRunning = false;\n            throw new IllegalStateException(\n                    String.format(\"Read snapshot for split %s fail\", split));\n        }\n\n        boolean changed =\n                changeEventSourceContext\n                        .getHighWatermark()\n                        .isAfter(changeEventSourceContext.getLowWatermark());\n        if (!sourceFetchContext.isExactlyOnce()) {\n            taskRunning = false;\n            if (changed) {\n                log.debug(\"Skip merge changelog(exactly-once) for snapshot split {}\", split);\n            }\n            return;\n        }\n\n        final IncrementalSplit backfillSplit = createBackfillBinlogSplit(changeEventSourceContext);\n        // optimization that skip the binlog read when the low watermark equals high\n        // watermark","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/source/reader/fetch/scan/MySqlSnapshotFetchTask.java#L60-L96","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the preceding logs for the root cause (SQL exception, connection loss) in MySqlSnapshotSplitReadTask.createDataEventsForTable","Re-run the job; snapshot splits are retriable from the last checkpoint","Increase JDBC connection/socket timeouts and stabilize the network between SeaTunnel and MySQL","Reduce snapshot split size so each chunk query completes faster"],"exampleFix":"// before\nthrow new IllegalStateException(String.format(\"Read snapshot for split %s fail\", split));\n// after\n// keep the error but surface the underlying cause:\nthrow new IllegalStateException(String.format(\"Read snapshot for split %s fail, last error: %s\", split, snapshotResult.getError().orElse(null)));","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Job-level: rely on SeaTunnel checkpoint restart; wrap submission with retry\ntry {\n    seatunnelClient.submitJob(jobConfig);\n} catch (Exception e) {\n    // retry with backoff; snapshot splits resume from checkpoint\n}","preventionTips":["Keep the MySQL connection stable; tune socket/connect timeouts","Reduce split size for large tables","Avoid killing long-running snapshot sessions (max_execution_time, DBA kill)","Run the job with checkpointing enabled so splits can resume"],"tags":["mysql","cdc","snapshot","illegal-state"],"backgroundTag":"invalid-state-transition","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}