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

IncrementalSourceStreamFetcher (incremental/binlog phase) captures exceptions from its streaming task into readException; checkReadException(), called from pollSplitRecords, rethrows it as SeaTunnelException with the incremental split id. It is the streaming-phase analogue of the scan fetcher's read-exception rethrow, surfacing asynchronous stream failures at the record-polling site.

Source

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

     * <p>Before event batch: [a, b, c, SchemaChangeEvent-1, SchemaChangeEvent-2, d, e]
     *
     * <p>After event batch: [a, b, c, checkpoint-before] [SchemaChangeEvent-1, SchemaChangeEvent-2,
     * checkpoint-after] [d, e]
     *
     * <p>For example 2:
     *
     * <p>Before event batch: [SchemaChangeEvent-1, SchemaChangeEvent-2, a, b, c, d, e]
     *
     * <p>After event batch: [checkpoint-before] [SchemaChangeEvent-1, SchemaChangeEvent-2,
     * checkpoint-after] [a, b, c, d, e]
     */
    Iterator<SourceRecords> splitSchemaChangeStream(List<DataChangeEvent> batchEvents) {
        return new SchemaChangeStreamSplitter().split(batchEvents);
    }

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

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

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read e.getCause() on the SeaTunnelException for the true replication error (e.g. 'binlog purged', 'replication slot does not exist').
2. For binlog purged: increase binlog retention (expire_logs_days / binlog_expire_logs_seconds) and restart the job from snapshot.
3. For PostgreSQL: recreate the replication slot and ensure wal_level=logical and adequate max_slot_wal_keep_size.
4. Verify replication credentials and privileges, then restart from the last checkpoint.

Example fix

// diagnose root cause
try {
    records = streamFetcher.pollSplitRecords();
} catch (SeaTunnelException e) {
    log.error("Incremental split {} failed: {}", e.getCause());
    throw e;
}

-- preflight checks
-- MySQL: SHOW VARIABLES LIKE 'log_bin'; ensure binlog retained
-- PostgreSQL: SELECT slot_name FROM pg_replication_slots;

try {
    records = streamFetcher.pollSplitRecords();
} catch (SeaTunnelException e) {
    log.error("Incremental read failed, root cause: {}", e.getCause());
    throw e;
}

When it happens

Trigger: The incremental (binlog/WAL) streaming task throws (replication stream disconnected, server closed binlog, deserialization error, replication slot dropped); the next pollSplitRecords call rethrows the stored exception.

Common situations: MySQL purged binlog files the stream still needs; PostgreSQL replication slot was dropped or wal_level insufficient; replication user privileges changed; long incremental phase exceeded server timeouts.

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

• Cannot read the binlog filename and position via '${showMast
• MySQL-CDC diagnostic: required binlog sequence {}{} is newer
• Unexpected error while connecting to MySQL and looking at gt
• Unexpected error while connecting to MySQL and looking for b
• Unexpected error while connecting to MySQL and looking at BI

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