apache/seatunnel · error · RuntimeException

SplitFetcher thread received unexpected exception while…

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().

Solutions

  1. Read the cause of this exception — it is always a wrap; the real failure is in the nested stack trace
  2. Fix the underlying SplitReader exception identified by the cause (schema, serde, connection)
  3. Upgrade/patch the connector if the cause indicates a library bug (NPE in fetch path)
  4. 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

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.

Appendix: 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)