apache/flink · error · IllegalArgumentException

The number of partitions must be at least 1.

Error message

The number of partitions must be at least 1.

What it means

LongValueSequenceIterator implements the SplittableIterator contract via split(numPartitions), which divides the remaining [current, to] range into numPartitions sub-iterators for parallel reading. numPartitions < 1 is rejected with IllegalArgumentException because zero or negative partitions have no meaningful split semantics.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/LongValueSequenceIterator.java:105

    @Override
    public LongValue next() {
        if (current <= to) {
            currentValue.setValue(current++);
            return currentValue;
        } else {
            throw new NoSuchElementException();
        }
    }

    @Override
    public void remove() {
        throw new UnsupportedOperationException();
    }

    @Override
    public LongValueSequenceIterator[] split(int numPartitions) {
        if (numPartitions < 1) {
            throw new IllegalArgumentException("The number of partitions must be at least 1.");
        }

        if (numPartitions == 1) {
            return new LongValueSequenceIterator[] {new LongValueSequenceIterator(current, to)};
        }

        // here, numPartitions >= 2 !!!

        long elementsPerSplit;

        if (to - current + 1 >= 0) {
            elementsPerSplit = (to - current + 1) / numPartitions;
        } else {
            // long overflow of the range.
            // we compute based on half the distance, to prevent the overflow.
            // in most cases it holds that: current < 0 and to > 0, except for: to == 0 and current
            // == Long.MIN_VALUE
            // the later needs a special case

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Trace where numPartitions comes from and guarantee it is >= 1 before calling split (e.g. Math.max(1, computedPartitions)).
2. Fix the upstream config: set explicit parallelism / number of splits instead of relying on defaults that can be 0.
3. Guard the exhausted-range case: return an empty split array yourself when there is nothing left rather than passing 0 down.
4. Add a unit test asserting split(1) and split(2) work and split(0)/split(-1) throw.

Example fix

// before
LongValueSequenceIterator[] parts = iterator.split(numSplits); // numSplits may be 0

// after
int safeSplits = Math.max(1, numSplits);
LongValueSequenceIterator[] parts = iterator.split(safeSplits);

int n = Math.max(1, numPartitions);
LongValueSequenceIterator[] parts = iterator.split(n);

When it happens

Trigger: Calling split(n) with n <= 0 — typically because the parallelism or split-count used to compute n was itself zero/unset (e.g. default int value from a missing config, or arithmetic that produced 0 for small inputs).

Common situations: Input format parallelism configured to 0 (implicit default when a field is never set); min(partitionCount, remainingElements) evaluating to 0 when the range is exhausted; downstream code deriving partition counts from collection sizes that are empty.

Related errors

• The number of partitions must be at least 1.
• Currently, filesystem sink doesn't support setting paralleli
• Parallelism must be at least one, or ExecutionConfig.PARALLE
• TaskNumber: {}, numTasks: {}
• The 'to' value must not be smaller than the 'from' value.

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