apache/seatunnel · error · RuntimeException

Flush ErrorHandler for transform stage failed

Error message

Flush ErrorHandler for transform stage failed

What it means

flushErrorHandler() flushes buffered error records of the transform stage's ErrorHandler, either globally (no checkpoint) or up to a checkpointId. Any exception from flush is wrapped in a RuntimeException with this message, failing the calling task flow (received() or flush paths).

Solutions

1. Inspect the cause for the actual sink error and restore the error-output target (network, credentials, disk space).
2. Confirm the error sink config (type, URL/path, auth) is valid in the job config.
3. Avoid closing the transform while flush is in flight (ordering of close vs barrier flush).
4. If error volume is huge, throttle error output or sample to avoid sink overload.

Example fix

// before: raw flush may fail the whole flow on transient sink errors
errorHandler.flush(checkpointId);
// after: add bounded retry for transient sink errors
for (int i = 0; i < 3; i++) {
    try { errorHandler.flush(checkpointId); return; }
    catch (Exception retryEx) { sleep(1000L * (i + 1)); }
}
throw new RuntimeException("Flush ErrorHandler for transform stage failed", lastEx);

try { flushErrorHandler(checkpointId); } catch (RuntimeException e) { if (e.getMessage().startsWith("Flush ErrorHandler")) { retryFlushWithBackoff(checkpointId); } else { throw e; } }

When it happens

Trigger: flushErrorHandler() called from received() (per-record) or checkpoint flush; underlying errorHandler.flush()/flush(checkpointId) throws because the error sink is unavailable, serialization fails, or the writer is closed.

Common situations: Error-output sink outage while error records are being written; error sink storage full; serialization issue in error payload; sink closed prematurely during concurrent flush and close.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Close ErrorHandler for transform stage failed
• FLUSH_DATA_FAILED
• FLUSH_DATA_FAILED
• FLUSH_DATA_FAILED
• Flush data into clickhouse file error

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/flow/TransformFlowLifeCycle.java:391

        super.close();
    }

    private void flushErrorHandler() {
        flushErrorHandler(null);
    }

    private void flushErrorHandler(Long checkpointId) {
        if (errorHandler == null) {
            return;
        }
        try {
            if (checkpointId == null) {
                errorHandler.flush();
            } else {
                errorHandler.flush(checkpointId);
            }
        } catch (Exception e) {
            throw new RuntimeException("Flush ErrorHandler for transform stage failed", e);
        }
    }

    private void snapshotErrorHandler(long checkpointId) {
        if (errorHandler != null) {
            errorHandler.snapshotState(checkpointId);
        }
    }

    @Override
    public void notifyCheckpointComplete(long checkpointId) {
        if (errorHandler != null) {
            errorHandler.notifyCheckpointComplete(checkpointId);
        }
    }

    @Override
    public void notifyCheckpointAborted(long checkpointId) {

View on GitHub (pinned to cf67b549a7)