{"record":{"id":"dbc907a932b21ef9","repo":"apache/seatunnel","slug":"read-snapshot-for-split-s-fail-dbc907","errorCode":null,"errorMessage":"Read snapshot for split %s fail","messagePattern":"Read snapshot for split (.+?) fail","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/source/reader/fetch/scan/SqlServerSnapshotFetchTask.java","lineNumber":79,"sourceCode":"                new SqlServerSnapshotSplitReadTask(\n                        sourceFetchContext.getDbzConnectorConfig(),\n                        sourceFetchContext.getOffsetContext(),\n                        sourceFetchContext.getSnapshotChangeEventSourceMetrics(),\n                        sourceFetchContext.getDatabaseSchema(),\n                        sourceFetchContext.getDataConnection(),\n                        sourceFetchContext.getDispatcher(),\n                        split);\n        SnapshotSplitChangeEventSourceContext changeEventSourceContext =\n                new SnapshotSplitChangeEventSourceContext();\n\n        SnapshotResult<SqlServerOffsetContext> 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 (!context.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 = createBackFillLsnSplit(changeEventSourceContext);\n        // optimization that skip the binlog read when the low watermark equals high\n        // watermark","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/source/reader/fetch/scan/SqlServerSnapshotFetchTask.java#L61-L97","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check SQL Server connectivity and stability between worker and database during snapshot; fix network/timeout issues","Inspect preceding log lines from SqlServerSnapshotSplitReadTask for the underlying cause (query failure, cancelled snapshot)","Retry the job; if reproducible, reduce snapshot parallelism or chunk size to lower load per split","Upgrade the connector version — early versions had snapshot retry bugs"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before submitting, confirm the table is snapshotable and connection is stable\ntry (Connection c = DriverManager.getConnection(url, user, pass)) {\n    if (!c.isValid(10)) throw new IllegalStateException(\"SQL Server unreachable\");\n    try (Statement s = c.createStatement();\n         ResultSet rs = s.executeQuery(\"SELECT COUNT(*) FROM \" + table)) {\n        rs.next();\n        System.out.println(\"rows=\" + rs.getLong(1));\n    }\n}","typeGuard":null,"tryCatchPattern":"// Wrap job submission/restart in retry\ntry {\n    submitJob(cfg);\n} catch (Exception e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Read snapshot for split\")) {\n        retryWithBackoff(() -> submitJob(cfg), 3);\n    } else throw e;\n}","preventionTips":["Ensure stable network between SeaTunnel workers and SQL Server during snapshot","Reduce snapshot chunk size to shorten each split read","Monitor Debezium task logs for cancel/failures before this throw","Keep connector and Debezium versions up to date"],"tags":["cdc","sqlserver","snapshot","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"}