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

NumberSequenceIterator.split(numPartitions) requires at least one partition; values < 1 throw IllegalArgumentException. The method implements the splittable-parallel-source contract and is called by the runtime with the source parallelism. A zero/negative parallelism reaching this point means upstream config or logic is wrong.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/NumberSequenceIterator.java:100

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

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

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

        if (numPartitions == 1) {
            return new NumberSequenceIterator[] {new NumberSequenceIterator(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. Ensure parallelism for the sequence source is at least 1.
2. Clamp computed parallelism: Math.max(1, requestedParallelism).
3. Check the config key feeding the parallelism (missing options can yield 0 in custom code).

Example fix

// before
int par = config.get("source.parallelism", 0);
NumberSequenceIterator[] parts = new NumberSequenceIterator(1, 1000).split(par);

// after
int par = Math.max(1, config.get("source.parallelism", 1));
NumberSequenceIterator[] parts = new NumberSequenceIterator(1, 1000).split(par);

int safePar = Math.max(1, requestedParallelism);
NumberSequenceIterator[] parts = source.split(safePar);

When it happens

Trigger: Calling split(0) or split(-1), e.g. generateSequence(...).setParallelism(0) flowing into source splitting; passing an unconfigured int that defaults to 0.

Common situations: Parallelism read from a missing config option defaulting to 0; dynamic parallelism computed as max(0, demand) and not clamped to >= 1; test harnesses invoking split directly.

Related errors

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

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