apache/seatunnel · error · RuntimeException

SplitFetcher thread %d received unexpected exception while p

Error message

SplitFetcher thread %d received unexpected exception while polling the records

What it means

SplitFetcher.runOnce() executes the current SplitFetcherTask outside the fetcher lock. Any unexpected Exception thrown by the task is wrapped in a RuntimeException carrying this formatted message including the fetcher thread id, then stored as an uncaught exception that later fails the source via checkErrors().

Source

Thrown at seatunnel-connectors-v2/connector-common/src/main/java/org/apache/seatunnel/connectors/seatunnel/common/source/reader/fetcher/SplitFetcher.java:164

            nextTask = getNextTaskUnsafe();
            if (nextTask == null) {
                // (spurious) wakeup, so just repeat
                return true;
            }

            log.debug("Prepare to run {}", nextTask);
            // store task for #wakeUp
            this.runningTask = nextTask;
        } finally {
            lock.unlock();
        }

        // execute the task outside of lock, so that it can be woken up
        try {
            nextTask.run();
        } catch (Exception e) {
            throw new RuntimeException(
                    String.format(
                            "SplitFetcher thread %d received unexpected exception while polling the records",
                            fetcherId),
                    e);
        }

        // re-acquire lock as all post-processing steps, need it
        lock.lock();
        try {
            this.runningTask = null;
        } finally {
            lock.unlock();
        }
        return true;
    }

    private SplitFetcherTask getNextTaskUnsafe() {
        if (!lock.isHeldByCurrentThread()) {

View on GitHub (pinned to cf67b549a7)

Solutions

Read the cause of this exception — it is always a wrap; the real failure is in the nested stack trace
Fix the underlying SplitReader exception identified by the cause (schema, serde, connection)
Upgrade/patch the connector if the cause indicates a library bug (NPE in fetch path)
Add validation of source records/schema before reading to catch serde issues early

Defensive patterns

Strategy: try-catch

Validate before calling

// validate splits/records before feeding fetcher
splits.forEach(s -> Objects.requireNonNull(s.splitId(), "split must have id"));

Try / catch

try {
    splitFetcherManager.checkErrors();
} catch (RuntimeException e) {
    Throwable cause = e.getCause(); // real failure from FetchTask/SplitReader
    throw new SourceException("root fetch failure: " + cause, cause);
}

Prevention

Always read the cause chain — this message is only a wrapper
Null-check state used inside custom SplitReader.fetch() implementations
Test connectors with malformed data to catch serde NPEs before production
Keep SplitReader free of connector-specific unchecked throws where possible

When it happens

Trigger: nextTask.run() throws any RuntimeException/Error not already converted to IOException by FetchTask — e.g. deserialization errors, connector-specific runtime failures inside SplitReader.fetch(), or NullPointerExceptions in split handling.

Common situations: Malformed records causing serde exceptions; connector bug (NPE) in SplitReader; schema drift between source and expected SeaTunnelRow type; OOM-adjacent errors during record batching.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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