apache/seatunnel · error · IOException

java.io.IOException

Error message

java.io.IOException

What it means

ErrorHandlingSinkWriter.flushErrorHandler wraps any exception thrown by the configured ErrorHandler during flush() in a java.io.IOException and rethrows it (ErrorHandlingSinkWriter.java:208-221, wrapped at 219). A non-IOException failure from the error-handling sink (e.g. the error data writer failing) is converted via toIOException(Exception) which nests the cause. Callers are snapshotState(long) and flushErrorHandler, i.e. this surfaces during checkpoint snapshotting or explicit flush.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/error/ErrorHandlingSinkWriter.java:219

        }
    }

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

    private void flushErrorHandler(Long checkpointId) throws IOException {
        if (errorHandler == null) {
            return;
        }
        try {
            if (checkpointId == null) {
                errorHandler.flush();
            } else {
                errorHandler.flush(checkpointId);
            }
        } catch (Exception e) {
            throw toIOException(e);
        }
    }

    private IOException toIOException(Exception e) {
        if (e instanceof IOException) {
            return (IOException) e;
        }
        return new IOException(e);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the IOException's cause chain (getCause()) - the real failure from the ErrorHandler is nested there.
2. Verify the error-handling sink target is reachable, writable, and correctly configured (error table/file path, credentials).
3. Fix or wrap exceptions correctly in custom ErrorHandler implementations; throwing IOException directly preserves the original error.
4. Re-run the checkpoint after the error sink recovers; the failing rows are retried from checkpoint state.
5. Test the error sink write path independently before running the pipeline to catch config problems early.

Example fix

// before: swallowing diagnostic detail
} catch (Exception e) {
    throw new IOException("flush failed");
}
// after: wrap the real cause so callers can diagnose
} catch (Exception e) {
    throw new IOException("ErrorHandler flush failed for checkpoint " + checkpointId, e);
}

// before running the pipeline, verify the error sink target is writable
try (Writer w = new OutputStreamWriter(new FileOutputStream(errorSinkPath, true), UTF_8)) {
    w.write("healthcheck\n");
}

try {
    sinkWriter.snapshotState(checkpointId);
} catch (IOException e) {
    Throwable root = e;
    while (root.getCause() != null) root = root.getCause();
    log.error("ErrorHandler flush failed during checkpoint {}; root cause: {}",
              checkpointId, root.getMessage(), e);
    throw e; // let the checkpoint fail and retry after the error sink recovers
}

When it happens

Trigger: errorHandler.flush(checkpointId) or errorHandler.flush() throws (e.g. the error sink cannot write failed rows to its target), and the exception is not already an IOException, so line 219 wraps it in IOException; triggered from snapshotState(checkpointId) during checkpoint or from the no-checkpointId flush path.

Common situations: Error-output sink (error table/file) unavailable or misconfigured while the main sink's error handler tries to persist bad rows; permission or connectivity problems on the error-data store; an unchecked exception (NPE, class cast) inside a custom ErrorHandler implementation surfaced as IOException at checkpoint time.

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

• WRITER_OPERATION_FAILED
• Single file mode is not supported when checkpoint is enabled
• Failed to flush data in prepareCommit
• Failed to flush data during prepareCommit()
• Failed to close equality delta writer

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