apache/flink · error · IllegalArgumentException

The timeout for opening the input splits must be positive…

Error message

The timeout for opening the input splits must be positive or zero (= infinite).

What it means

openTimeout caps how long the format waits for a filesystem stream to open before failing (e.g. slow remote filesystems). Zero means infinite wait (no timeout), which is allowed. Negative values are meaningless, so FileInputFormat.setOpenTimeout rejects them with IllegalArgumentException.

Solutions

1. Pass 0 for infinite wait, or a positive millisecond value (e.g. format.setOpenTimeout(60_000)).
2. Coerce: openTimeout = configured >= 0 ? configured : 0.
3. Leave the default (DEFAULT_OPENING_TIMEOUT from FS_STREAM_OPENING_TIME_OUT) if unsure.

Example fix

// before
format.setOpenTimeout(timeoutMs); // timeoutMs == -1 -> throws

// after
long t = timeoutMs >= 0 ? timeoutMs : 0;
format.setOpenTimeout(t);

long t = openTimeout >= 0 ? openTimeout : 0;
format.setOpenTimeout(t);

When it happens

Trigger: Calling format.setOpenTimeout(-1) or any negative long.

Common situations: Passing -1 intending 'infinite' (the infinite sentinel is 0, not -1); computing the timeout from a config that uses -1 as 'undefined'; subtracting deltas that underflow.

Understand the failure class

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

Related errors

• At least one file path must be specified.
• Buffer size must be at least 2.
• Buffer size must be greater than length of delimiter.
• Delimiter must not be null
• File path cannot be null.

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

Appendix: source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/io/FileInputFormat.java:347

        return numSplits;
    }

    public void setNumSplits(int numSplits) {
        if (numSplits < -1 || numSplits == 0) {
            throw new IllegalArgumentException(
                    "The desired number of splits must be positive or -1 (= don't care).");
        }

        this.numSplits = numSplits;
    }

    public long getOpenTimeout() {
        return openTimeout;
    }

    public void setOpenTimeout(long openTimeout) {
        if (openTimeout < 0) {
            throw new IllegalArgumentException(
                    "The timeout for opening the input splits must be positive or zero (= infinite).");
        }
        this.openTimeout = openTimeout;
    }

    public void setNestedFileEnumeration(boolean enable) {
        this.enumerateNestedFiles = enable;
    }

    public boolean getNestedFileEnumeration() {
        return this.enumerateNestedFiles;
    }

    // --------------------------------------------------------------------------------------------
    // Getting information about the split that is currently open
    // --------------------------------------------------------------------------------------------

    /**

View on GitHub (pinned to 2f3c205e92)