What causes "The parallelism must be a positive number: {}" in apache/flink?

apache/flink · error · CliArgsException

The parallelism must be a positive number: {}

Error message

The parallelism must be a positive number: {}

What it means

Thrown by ProgramOptions constructor when the --parallelism (-p) value parses as an integer but is <= 0 and not equal to ExecutionConfig.PARALLELISM_DEFAULT (-1). Flink requires positive parallelism for actual execution; -1 is the special sentinel meaning 'use default'. The NumberFormatException (internally thrown for invalid values) is caught and re-thrown as CliArgsException with a descriptive message.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/cli/ProgramOptions.java:106

                try {
                    classpaths.add(new URL(path));
                } catch (MalformedURLException e) {
                    throw new CliArgsException("Bad syntax for classpath: " + path);
                }
            }
        }
        this.classpaths = classpaths;

        if (line.hasOption(PARALLELISM_OPTION.getOpt())) {
            hasParallelismOpt = true;
            String parString = line.getOptionValue(PARALLELISM_OPTION.getOpt());
            try {
                parallelism = Integer.parseInt(parString);
                if (parallelism <= 0 && parallelism != ExecutionConfig.PARALLELISM_DEFAULT) {
                    throw new NumberFormatException();
                }
            } catch (NumberFormatException e) {
                throw new CliArgsException(
                        "The parallelism must be a positive number: " + parString);
            }
        } else {
            hasParallelismOpt = false;
            parallelism = ExecutionConfig.PARALLELISM_DEFAULT;
        }

        detachedMode = line.hasOption(DETACHED_OPTION.getOpt());
        shutdownOnAttachedExit = line.hasOption(SHUTDOWN_IF_ATTACHED_OPTION.getOpt());

        this.savepointSettings = CliFrontendParser.createSavepointRestoreSettings(line);
    }

    protected String[] extractProgramArgs(CommandLine line) {
        String[] args =
                line.hasOption(ARGS_OPTION.getOpt())
                        ? line.getOptionValues(ARGS_OPTION.getOpt())
                        : line.getArgs();

View on GitHub (pinned to 2f3c205e92)

Solutions

Use a positive integer: `-p 4`
Omit -p entirely to use the default parallelism from flink-conf.yaml
Use -p -1 explicitly if you want the framework default (though omitting is clearer)

Example fix

// before
flink run -p 0 ./job.jar

// after
flink run -p 4 ./job.jar
// or omit to use config default
flink run ./job.jar

Defensive patterns

Strategy: validation

Validate before calling

int parallelism = Integer.parseInt(parString);
if (parallelism <= 0 && parallelism != ExecutionConfig.PARALLELISM_DEFAULT) {
    throw new IllegalArgumentException(
        "Parallelism must be positive or -1 (default). Got: " + parallelism);
}

Prevention

Use positive integers only for -p
Omit -p to use the default parallelism from configuration
Validate computed parallelism values in scripts before passing to the CLI

When it happens

Trigger: Passing `-p 0` or `-p -5`; passing a non-numeric string like `-p abc` which causes Integer.parseInt to throw NumberFormatException, caught and re-thrown with the same message.

Common situations: Scripts that compute parallelism from a variable that resolves to zero or negative; users who think -p 0 means 'use all slots'; typo or truncation in CI pipeline parameters.

Related errors

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