apache/seatunnel · error · IllegalStateException

Read snapshot for oracle split

Error message

Read snapshot for oracle split %s fail

What it means

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.

Solutions

1. Inspect earlier log lines for the underlying error from the snapshot read task
2. Re-run the job; snapshot splits are retried on failure
3. Ensure the snapshot user has SELECT privileges on the table and the table is stable (not being DDL-altered) during snapshot
4. Reduce snapshot split size to lower per-split failure risk on very large tables

// Before running snapshot, confirm table is readable and stable
try (ResultSet rs = stmt.executeQuery("SELECT 1 FROM " + tableId + " WHERE 1=0")) { /* readable */ }

try {
    fetchTask.execute(context);
} catch (IllegalStateException e) {
    LOG.warn("Snapshot split {} failed, will be retried", splitId, e);
    // rely on framework retry or re-enqueue the split
}

When it happens

Trigger: 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.

Common situations: 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.

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
• Read snapshot for split
• Snapshotting of table
• Cannot convert timestamp to SCN. Make sure the specified…
• Cannot find table schema for table

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/source/reader/fetch/scan/OracleSnapshotFetchTask.java:95

        snapshotSplitReadTask =
                new OracleSnapshotSplitReadTask(
                        sourceFetchContext.getDbzConnectorConfig(),
                        sourceFetchContext.getOffsetContext(),
                        sourceFetchContext.getSnapshotChangeEventSourceMetrics(),
                        sourceFetchContext.getDatabaseSchema(),
                        sourceFetchContext.getConnection(),
                        sourceFetchContext.getDispatcher(),
                        split);
        SnapshotSplitChangeEventSourceContext changeEventSourceContext =
                new SnapshotSplitChangeEventSourceContext();
        SnapshotResult<OracleOffsetContext> snapshotResult =
                snapshotSplitReadTask.execute(
                        changeEventSourceContext,
                        sourceFetchContext.getPartition(),
                        sourceFetchContext.getOffsetContext());
        if (!snapshotResult.isCompletedOrSkipped()) {
            taskRunning = false;
            throw new IllegalStateException(
                    String.format("Read snapshot for oracle split %s fail", split));
        }

        boolean changed =
                changeEventSourceContext
                        .getHighWatermark()
                        .isAfter(changeEventSourceContext.getLowWatermark());
        if (!context.isExactlyOnce()) {
            taskRunning = false;
            if (changed) {
                log.debug("Skip merge changelog(exactly-once) for snapshot split {}", split);
            }
            return;
        }

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

View on GitHub (pinned to cf67b549a7)