What causes "One or more fetchers have encountered exception" in apache/seatunnel?

Inspect getCause() — this is always a wrapper; the root error is the fetcher's original exception

apache/seatunnel · critical · RuntimeException

One or more fetchers have encountered exception

Error message

One or more fetchers have encountered exception

What it means

SplitFetcherManager stores the first uncaught exception from any fetcher thread in an AtomicReference. checkErrors() is polled by the source reader on each record-emission cycle; if a fetcher failed, it rethrows that stored exception wrapped in this RuntimeException so the whole source fails fast.

Source

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

        }
        return fetchers.isEmpty();
    }

    public synchronized void close(long timeoutMs) throws Exception {
        closed = true;
        fetchers.values().forEach(SplitFetcher::shutdown);
        executors.shutdown();
        if (!executors.awaitTermination(timeoutMs, TimeUnit.MILLISECONDS)) {
            log.warn(
                    "Failed to close the source reader in {} ms. There are still {} split fetchers running",
                    timeoutMs,
                    fetchers.size());
        }
    }

    public void checkErrors() {
        if (uncaughtFetcherException.get() != null) {
            throw new RuntimeException(
                    "One or more fetchers have encountered exception",
                    uncaughtFetcherException.get());
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect getCause() — this is always a wrapper; the root error is the fetcher's original exception
Fix the underlying source problem identified by the cause (network, credentials, serde)
Add retry/backoff inside the SplitReader for transient source errors so one blip doesn't kill the fetcher
Check earlier logs for the fetcher thread's stack trace, which fires before this aggregate error

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight source health check before polling
if (!fetcherManagerHealthy()) {
    throw new IllegalStateException("source fetchers unhealthy before job start");
}

Try / catch

try {
    splitFetcherManager.checkErrors();
} catch (RuntimeException e) {
    Throwable root = e.getCause();
    if (root instanceof java.io.IOException && isTransient(root)) {
        restartFetcher(); // retry path
    } else {
        throw e;
    }
}

Prevention

Always inspect the cause — the real fetcher failure is nested
Implement retry/backoff in SplitReader for transient network/source errors
Monitor fetcher thread health and logs before this aggregate error surfaces
Ensure deserializers are validated against source schema at job start

When it happens

Trigger: Any fetcher thread died with an exception (see SplitFetcher.run / FetchTask.run failures), and the main reader thread subsequently calls checkErrors() — the original cause is in the nested stack trace.

Common situations: Source connectivity loss (Kafka broker down, JDBC timeout) inside SplitReader; deserialization errors in the fetch path; interruption during shutdown surfacing here after the job already failed elsewhere.

Related errors

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