apache/flink · error · RuntimeException

One or more fetchers have encountered exception

Error message

One or more fetchers have encountered exception

What it means

SplitFetcherManager#checkErrors throws a RuntimeException wrapping uncaughtFetcherException if any fetcher thread terminated with an uncaught exception. Source readers call this periodically to propagate fetch-thread failures to the main thread so the source fails fast rather than silently stalling.

Source

Thrown at flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/source/reader/fetcher/SplitFetcherManager.java:350

                                    e);
                            break;
                        }
                        timeElapsed = System.currentTimeMillis() - startTime;
                    }
                });
        executors.shutdown();
        long timeElapsed = System.currentTimeMillis() - startTime;
        if (!executors.awaitTermination(timeoutMs - timeElapsed, TimeUnit.MILLISECONDS)) {
            LOG.warn(
                    "Failed to close the split fetchers in {} ms. There are still {} split fetchers running",
                    timeoutMs,
                    fetchersToShutDown.get());
        }
    }

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

    // -----------------------

    @VisibleForTesting
    public int getNumAliveFetchers() {
        return fetchers.size();
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Inspect the wrapped cause (uncaughtFetcherException) to find the originating fetcher error and fix the underlying connector/data problem.
2. If the cause is transient, rely on the job restart strategy to recover after you resolve the external issue.
3. Verify the SplitReader handles recoverable errors internally so they do not kill the fetch thread.
4. Ensure checkErrors is being called in your source reader loop so failures are not swallowed.

try {
    splitFetcherManager.checkErrors();
} catch (RuntimeException e) {
    Throwable cause = e.getCause();
    // cause is the original uncaught fetcher exception; act on it
    throw e;
}

When it happens

Trigger: A SplitFetcher thread's UncaughtExceptionHandler recorded an exception (commonly the RuntimeException from error 123 or 124). The next time the source reader calls checkErrors(), the stored exception is rethrown.

Common situations: Any unhandled error in a SplitReader (network, deserialization, auth) that killed a fetch thread. The root cause is the wrapped uncaughtFetcherException.

Related errors

• SplitFetcher thread %d received unexpected exception while p
• Source fetch execution was interrupted
• The thread was interrupted while waiting for a fetcher task.
• This split reader does not support pausing or resuming split
• exception in queue future completion

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/af28a7082cd731ed. Report an issue: GitHub.