apache/flink · error · IllegalArgumentException

The desired number of splits must be positive or -1 (= don't

Error message

The desired number of splits must be positive or -1 (= don't care).

What it means

numSplits is the desired number of input splits. The format accepts any positive integer, and -1 as a 'don't care' sentinel (let the framework decide). Zero and values below -1 are invalid because they cannot express a real split count, so FileInputFormat.setNumSplits rejects them with IllegalArgumentException.

Source

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

    public long getMinSplitSize() {
        return minSplitSize;
    }

    public void setMinSplitSize(long minSplitSize) {
        if (minSplitSize < 0) {
            throw new IllegalArgumentException("The minimum split size cannot be negative.");
        }

        this.minSplitSize = minSplitSize;
    }

    public int getNumSplits() {
        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;
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Pass a positive integer for an explicit count, or -1 to let the framework decide.
2. Coerce invalid values: numSplits = desired > 0 ? desired : -1.
3. Do not call setNumSplits if you want the default (-1 / framework-decided).

Example fix

// before
format.setNumSplits(parallelism); // parallelism == 0 -> throws

// after
int n = parallelism > 0 ? parallelism : -1;
format.setNumSplits(n);

int n = (numSplits > 0) ? numSplits : -1;
format.setNumSplits(n);

When it happens

Trigger: Calling format.setNumSplits(0) or any value < -1 (e.g. -2).

Common situations: Passing 0 intending 'automatic' (the sentinel is -1, not 0); computing numSplits from parallelism that resolved to 0; misreading documentation and using -2 as 'unlimited'.

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/373c4b54230a0c3e. Report an issue: GitHub.