{"record":{"id":"fbd293e8c6289d9d","repo":"apache/seatunnel","slug":"read-snapshot-for-split-split-fail-fbd293","errorCode":null,"errorMessage":"Read snapshot for split ${split} fail","messagePattern":"Read snapshot for split (.+?) fail","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/postgres/source/reader/snapshot/PostgresSnapshotFetchTask.java","lineNumber":71,"sourceCode":"        snapshotSplitReadTask =\n                new PostgresSnapshotSplitReadTask(\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        SnapshotResult 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        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 = createBackFillWalSplit(changeEventSourceContext);\n        // optimization that skip the binlog read when the low watermark equals high\n        // watermark\n        // todo Add backfill task","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/postgres/source/reader/snapshot/PostgresSnapshotFetchTask.java#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rerun the job (snapshot splits are retried/resumable via checkpoint state).","Reduce snapshot chunk size to make each chunk read shorter and more reliable.","Verify the snapshot user has SELECT on all captured tables and stable connectivity to the DB.","Check for concurrent DDL/truncations on the table during snapshot and reschedule them.","Inspect the underlying reader logs for the root failure of the chunk read."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-check SELECT privilege on all captured tables\nSELECT has_table_privilege(current_user, 'public.orders', 'SELECT');","typeGuard":null,"tryCatchPattern":"try {\n    task.execute(ctx, partition, offsetContext);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Read snapshot for split\")) {\n        // retry the split or resubmit the job with smaller chunk size\n    }\n}","preventionTips":["Keep snapshot chunk sizes moderate for large tables","Ensure stable connectivity and adequate statement timeouts during snapshot","Avoid DDL on captured tables during snapshotting","Verify SELECT privileges for the snapshot user"],"tags":["postgresql","cdc","snapshot","split-read"],"backgroundTag":"internal-invariant-violation","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}