apache/seatunnel · error · IOException

Timed out after {} seconds while writing python.script.confi

Error message

Timed out after {} seconds while writing python.script.config; ensure the Python script reads its first stdin line

What it means

The Java↔Python contract requires the Python script to read its first stdin line, which carries python.script.config as JSON. If the child process does not consume that line within INITIAL_CONFIG_WRITE_TIMEOUT_SECONDS, the write cannot complete and the reader throws this IOException at open().

Source

Thrown at seatunnel-connectors-v2/connector-python/src/main/java/org/apache/seatunnel/connectors/seatunnel/python/source/PythonSourceReader.java:354

                        "python-source-stdin-writer");
        stdinWriterThread.setDaemon(true);
        stdinWriterThread.start();
    }

    /** Fails process initialization when the child does not consume the initial JSON contract. */
    private void waitForInitialConfigWrite() throws IOException {
        try {
            stdinWriterThread.join(TimeUnit.SECONDS.toMillis(INITIAL_CONFIG_WRITE_TIMEOUT_SECONDS));
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IOException("Interrupted while writing python.script.config", e);
        }

        if (closeRequested) {
            throw new IOException("Python source was closed while writing python.script.config");
        }
        if (!initialConfigWritten) {
            throw new IOException(
                    "Timed out after "
                            + INITIAL_CONFIG_WRITE_TIMEOUT_SECONDS
                            + " seconds while writing python.script.config; ensure the Python script reads its first stdin line");
        }
        if (stdinWriterFailure != null) {
            if (!process.isAlive()) {
                // A closed stdin pipe surfaces here as a generic write IOException (e.g. "Broken
                // pipe"), but the actual contract violation is that the script exited without
                // reading python.script.config; report that instead of the write symptom.
                throw new IOException(
                        "Python script exited before reading its first stdin line;"
                                + " python.script.config could not be delivered"
                                + formatRecentStderr(),
                        stdinWriterFailure);
            }
            throw new IOException("Failed to write python.script.config", stdinWriterFailure);
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

Make the Python script read its first stdin line at startup (e.g. json.loads(sys.stdin.readline())) before doing other work
Verify the script is the intended contract-compliant entrypoint
Test the script locally: echo '{...}' | python script.py should not block
Check script startup time against the configured timeout

Example fix

# before
import time
time.sleep(60)
config = json.loads(sys.stdin.readline())
# after
config = json.loads(sys.stdin.readline())  # read contract line first

Defensive patterns

Strategy: validation

Validate before calling

# contract check: script must read first stdin line immediately
echo '{}' | timeout 5 python your_script.py || echo 'script violates stdin contract'

Try / catch

try {
    reader.open();
} catch (IOException e) {
    if (e.getMessage().contains("Timed out")) {
        // script did not read stdin; fix script before retrying
    }
}

Prevention

Always read sys.stdin.readline() as the first action in the script
Avoid sleeps, prompts, or heavy imports before the stdin read
Test the script standalone with piped stdin before deploying

When it happens

Trigger: A Python script that never reads stdin (or reads it late — e.g. sleeps or imports heavy modules first), a script that blocks before its first stdin read, or a pipe buffering deadlock, causing waitForInitialConfigWrite to time out.

Common situations: Using a generic script not written against the SeaTunnel Python source contract; script has an interactive prompt or long startup; script was edited and the stdin read removed; wrong interpreter startup scripts delay main().

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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