apache/flink · 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 catches any Exception thrown by a SplitFetcherTask#run (typically FetchTask, which calls SplitReader#fetch) and re-throws it as a RuntimeException identifying the fetcher thread by id. This is the primary path by which errors inside a split reader surface from the fetch thread.

Source

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

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

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

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

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

    private void processTaskResultUnsafe(SplitFetcherTask task, boolean taskFinished) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Read the nested cause to find the real connector-level exception and address it (reconnect, fix data, refresh credentials).
2. If the cause is transient, configure the connector/source for retry or restart-strategy to recover automatically.
3. If the cause is a poison-pill record, enable side-output / DLQ or filter invalid data upstream.
4. Confirm the SplitReader implementation is not throwing for non-fatal conditions it should handle internally.

// In a custom SourceReader, surface fetcher errors explicitly:
splitFetcherManager.checkErrors();
try {
    // process records
} catch (RuntimeException e) {
    Throwable cause = e.getCause() != null ? e.getCause() : e;
    log.warn("Fetch task failed: {}", cause.toString());
    throw e;
}

When it happens

Trigger: SplitReader#fetch throws (network error, deserialization failure, auth expiry), or any AddSplitsTask / wakeup-related task throws during task.run(). The exception is set on the SplitFetcher and later surfaced via SplitFetcherManager#checkErrors.

Common situations: Connector read failure: broker disconnect, HTTP 4xx/5xx, malformed records, transient I/O errors, SplitReader misuse. The concrete cause is in the wrapped Throwable.

Related errors

• Source fetch execution was interrupted
• The thread was interrupted while waiting for a fetcher task.
• One or more fetchers have encountered exception
• 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/8f273998b3d5c636. Report an issue: GitHub.