{"record":{"id":"af350b0fdaf1ea92","repo":"apache/flink","slug":"the-parallelism-must-be-a-positive-number","errorCode":null,"errorMessage":"The parallelism must be a positive number: {}","messagePattern":"The parallelism must be a positive number: (.+?)","errorType":"validation","errorClass":"CliArgsException","httpStatus":null,"severity":"error","filePath":"flink-clients/src/main/java/org/apache/flink/client/cli/ProgramOptions.java","lineNumber":106,"sourceCode":"                try {\n                    classpaths.add(new URL(path));\n                } catch (MalformedURLException e) {\n                    throw new CliArgsException(\"Bad syntax for classpath: \" + path);\n                }\n            }\n        }\n        this.classpaths = classpaths;\n\n        if (line.hasOption(PARALLELISM_OPTION.getOpt())) {\n            hasParallelismOpt = true;\n            String parString = line.getOptionValue(PARALLELISM_OPTION.getOpt());\n            try {\n                parallelism = Integer.parseInt(parString);\n                if (parallelism <= 0 && parallelism != ExecutionConfig.PARALLELISM_DEFAULT) {\n                    throw new NumberFormatException();\n                }\n            } catch (NumberFormatException e) {\n                throw new CliArgsException(\n                        \"The parallelism must be a positive number: \" + parString);\n            }\n        } else {\n            hasParallelismOpt = false;\n            parallelism = ExecutionConfig.PARALLELISM_DEFAULT;\n        }\n\n        detachedMode = line.hasOption(DETACHED_OPTION.getOpt());\n        shutdownOnAttachedExit = line.hasOption(SHUTDOWN_IF_ATTACHED_OPTION.getOpt());\n\n        this.savepointSettings = CliFrontendParser.createSavepointRestoreSettings(line);\n    }\n\n    protected String[] extractProgramArgs(CommandLine line) {\n        String[] args =\n                line.hasOption(ARGS_OPTION.getOpt())\n                        ? line.getOptionValues(ARGS_OPTION.getOpt())\n                        : line.getArgs();","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-clients/src/main/java/org/apache/flink/client/cli/ProgramOptions.java#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nflink run -p 0 ./job.jar\n\n// after\nflink run -p 4 ./job.jar\n// or omit to use config default\nflink run ./job.jar","handlingStrategy":"validation","validationCode":"int parallelism = Integer.parseInt(parString);\nif (parallelism <= 0 && parallelism != ExecutionConfig.PARALLELISM_DEFAULT) {\n    throw new IllegalArgumentException(\n        \"Parallelism must be positive or -1 (default). Got: \" + parallelism);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","configuration","user-input"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}