{"record":{"id":"7a6330da9590ef2f","repo":"apache/seatunnel","slug":"read-snapshot-for-oracle-split-s-fail","errorCode":null,"errorMessage":"Read snapshot for oracle split %s fail","messagePattern":"Read snapshot for oracle split (.+?) fail","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/reader/fetch/scan/OracleSnapshotFetchTask.java","lineNumber":95,"sourceCode":"        snapshotSplitReadTask =\n                new OracleSnapshotSplitReadTask(\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<OracleOffsetContext> 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 oracle 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 = createBackfillRedoLogSplit(changeEventSourceContext);\n        // optimization that skip the redoLog read when the low watermark equals high\n        // watermark","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/reader/fetch/scan/OracleSnapshotFetchTask.java#L77-L113","documentation":"OracleSnapshotFetchTask.execute() runs the snapshot split read task and checks whether the result is completed or skipped. If the snapshot did not finish successfully, it throws IllegalStateException indicating the Oracle snapshot split failed. This aborts the snapshot phase for that split so the framework can retry or fail the job.","triggerScenarios":"The embedded snapshot read task (snapshotSplitReadTask.execute) returns a result that is not completedOrSkipped — typically because an error occurred during the snapshot query or the reader was interrupted/cancelled.","commonSituations":"Oracle connection dropped mid-snapshot; table being read was dropped or locked; LogMiner/schema issues during snapshot; task cancellation or checkpoint timeout during large-table snapshot.","solutions":["Inspect earlier log lines for the underlying error from the snapshot read task","Re-run the job; snapshot splits are retried on failure","Ensure the snapshot user has SELECT privileges on the table and the table is stable (not being DDL-altered) during snapshot","Reduce snapshot split size to lower per-split failure risk on very large tables"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before running snapshot, confirm table is readable and stable\ntry (ResultSet rs = stmt.executeQuery(\"SELECT 1 FROM \" + tableId + \" WHERE 1=0\")) { /* readable */ }","typeGuard":null,"tryCatchPattern":"try {\n    fetchTask.execute(context);\n} catch (IllegalStateException e) {\n    LOG.warn(\"Snapshot split {} failed, will be retried\", splitId, e);\n    // rely on framework retry or re-enqueue the split\n}","preventionTips":["Ensure SELECT privileges on all snapshot tables","Avoid DDL/drops during snapshot","Reduce snapshot fetch/split size for very large tables","Keep the job's checkpoint/retry settings enabled so failed splits retry"],"tags":["oracle-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-23T08:17:48.524Z"}