apache/flink · error · IllegalArgumentException

The timeout for opening the input splits must be positive or

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.

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)

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

• The block size parameter must be set and larger than 0.
• Delimiter must not be null
• Line length limit must be at least 1.
• Buffer size must be at least 2.
• Number of line samples must not be negative.

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