apache/flink · error · IllegalArgumentException

Parallelism must be at least one, or ExecutionConfig.PARALLE

Error message

Parallelism must be at least one, or ExecutionConfig.PARALLELISM_DEFAULT (use system default).

What it means

Thrown by ExecutionConfig.setParallelism when the value is neither PARALLELISM_UNKNOWN (-1, meaning leave unchanged) nor a valid positive number, nor PARALLELISM_DEFAULT (-1 used as 'use system default'). Any value < 1 that is not the DEFAULT sentinel is rejected because parallelism must be at least 1 task. The guard prevents nonsensical zero or negative parallelism that would break scheduling.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/ExecutionConfig.java:290

        return configuration.get(CoreOptions.DEFAULT_PARALLELISM);
    }

    /**
     * Sets the parallelism for operations executed through this environment. Setting a parallelism
     * of x here will cause all operators (such as join, map, reduce) to run with x parallel
     * instances.
     *
     * <p>This method overrides the default parallelism for this environment. The local execution
     * environment uses by default a value equal to the number of hardware contexts (CPU cores /
     * threads). When executing the program via the command line client from a JAR file, the default
     * parallelism is the one configured for that setup.
     *
     * @param parallelism The parallelism to use
     */
    public ExecutionConfig setParallelism(int parallelism) {
        if (parallelism != PARALLELISM_UNKNOWN) {
            if (parallelism < 1 && parallelism != PARALLELISM_DEFAULT) {
                throw new IllegalArgumentException(
                        "Parallelism must be at least one, or ExecutionConfig.PARALLELISM_DEFAULT (use system default).");
            }
            configuration.set(CoreOptions.DEFAULT_PARALLELISM, parallelism);
        }
        return this;
    }

    @Internal
    public void resetParallelism() {
        configuration.removeConfig(CoreOptions.DEFAULT_PARALLELISM);
    }

    /**
     * Gets the maximum degree of parallelism defined for the program.
     *
     * <p>The maximum degree of parallelism specifies the upper limit for dynamic scaling. It also
     * defines the number of key groups used for partitioned state.
     *

View on GitHub (pinned to 2f3c205e92)

Solutions

1. If you mean 'use the system/cl default', pass ExecutionConfig.PARALLELISM_DEFAULT rather than 0.
2. Compute parallelism defensively: int p = Math.max(1, requested) before calling setParallelism, or pass PARALLELISM_UNKNOWN to leave it unset.
3. Validate config values at the boundary (CLI parser, config loader) so 0 never reaches setParallelism.

Example fix

// before
executionConfig.setParallelism(configured);
// after
if (configured <= 0) {
    executionConfig.setParallelism(ExecutionConfig.PARALLELISM_DEFAULT);
} else {
    executionConfig.setParallelism(configured);
}

int p = (configured == ExecutionConfig.PARALLELISM_UNKNOWN
          || configured == ExecutionConfig.PARALLELISM_DEFAULT)
        ? configured
        : Math.max(1, configured);
executionConfig.setParallelism(p);

public static boolean isValidParallelism(int p) {
    return p == ExecutionConfig.PARALLELISM_UNKNOWN
        || p == ExecutionConfig.PARALLELISM_DEFAULT
        || p >= 1;
}

When it happens

Trigger: Calling executionConfig.setParallelism(0) or any negative value other than the sentinels; passing a parsed config value of 0 when an option defaulted unexpectedly; computing parallelism as max(a,b) where both were 0.

Common situations: Reading parallelism from a Configuration/CoreOptions key that returned 0; arithmetic on CPU counts that underflowed; users misreading PARALLELISM_DEFAULT semantics.

Related errors

• Currently, filesystem sink doesn't support setting paralleli
• TaskNumber: {}, numTasks: {}
• The number of partitions must be at least 1.
• The number of partitions must be at least 1.
• Option %s.%s is required for serialization

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