apache/seatunnel · error · org.apache.seatunnel.api.table.type.SeaTunnelException

Read split %s error due to %s.

Error message

Read split %s error due to %s.

What it means

IncrementalSourceScanFetcher runs snapshot scanning in a separate task thread; any exception thrown there is captured into readException. checkReadException(), invoked from pollSplitRecords/pollSplitRecordsIfExactlyOnce, rethrows it as SeaTunnelException wrapping the original cause, prefixed with the current snapshot split id. This converts an asynchronous reader failure into a synchronous failure visible at the poll site.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/source/reader/external/IncrementalSourceScanFetcher.java:215

        normalizedRecords.addAll(taskContext.formatMessageTimestamp(outputBuffer.values()));
        normalizedRecords.add(highWatermark);

        final List<SourceRecords> sourceRecordsSet = new ArrayList<>();
        sourceRecordsSet.add(new SourceRecords(normalizedRecords));
        return sourceRecordsSet.iterator();
    }

    private void assertLowWatermark(SourceRecord lowWatermark) {
        checkState(
                isLowWatermarkEvent(lowWatermark),
                String.format(
                        "The first record should be low watermark signal event, but actual is %s",
                        lowWatermark));
    }

    private void checkReadException() {
        if (readException != null) {
            throw new SeaTunnelException(
                    String.format(
                            "Read split %s error due to %s.",
                            currentSnapshotSplit, readException.getMessage()),
                    readException);
        }
    }

    @Override
    public void close() {
        try {
            // 1. try close the split task
            if (snapshotSplitReadTask != null) {
                try {
                    snapshotSplitReadTask.shutdown();
                } catch (Exception e) {
                    log.error("Close snapshot split read task error", e);
                }
            }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the cause (readException) via the SeaTunnelException's cause chain; it carries the real database/driver error.
  2. Fix the underlying database issue: restore connectivity, grant SELECT on the captured table, or resolve the schema mismatch.
  3. Enable checkpointing and restart the job so the snapshot split is re-scanned from its last restored position.
  4. Increase connection/socket timeouts if the scan of very large tables routinely exceeds them.

Example fix

// before: failing poll
SourceRecords records = scanFetcher.pollSplitRecords();
// after: catch and inspect root cause
try {
    SourceRecords records = scanFetcher.pollSplitRecords();
} catch (SeaTunnelException e) {
    Throwable root = e.getCause(); // actual JDBC/driver error
    throw new IOException("Snapshot split read failed: " + root.getMessage(), root);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: verify DB connectivity and SELECT privilege before job start
// SELECT COUNT(*) FROM <captured-table> LIMIT 1;

Try / catch

try {
    records = scanFetcher.pollSplitRecords();
} catch (SeaTunnelException e) {
    Throwable cause = e.getCause();
    log.error("Snapshot split read failed: {}", cause, cause);
    throw e;
}

Prevention

When it happens

Trigger: The background scan task for a snapshot split fails (JDBC read error, binlog/LSN access error, deserialization failure, connection loss); the next call to pollSplitRecords detects the stored readException and rethrows it.

Common situations: Database connection dropped mid-scan; user lacks SELECT permission on part of the table; split range query fails due to schema change while the snapshot was running; network timeout between SeaTunnel worker and database.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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