{"record":{"id":"4b9200afdb7732e9","repo":"apache/pulsar","slug":"number-of-messages-should-be-zero-or-positive","errorCode":null,"errorMessage":"Number of messages should be zero or positive.","messagePattern":"Number of messages should be zero or positive\\.","errorType":"validation","errorClass":"CommandLine.ParameterException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdConsume.java","lineNumber":163,"sourceCode":"    public CmdConsume() {\n        // Do nothing\n        super();\n    }\n\n    @Spec\n    private CommandSpec commandSpec;\n\n    /**\n     * Run the consume command.\n     *\n     * @return 0 for success, < 0 otherwise\n     */\n    public int run() throws IOException {\n        if (this.subscriptionName == null || this.subscriptionName.isEmpty()) {\n            throw new CommandLine.ParameterException(commandSpec.commandLine(), \"Subscription name is not provided.\");\n        }\n        if (this.numMessagesToConsume < 0) {\n            throw new CommandLine.ParameterException(commandSpec.commandLine(),\n                    \"Number of messages should be zero or positive.\");\n        }\n        if (this.endTimestamp < 0) {\n            throw new CommandLine.ParameterException(commandSpec.commandLine(),\n                    \"end timestamp should be positive.\");\n        }\n\n        if (this.serviceURL.startsWith(\"ws\")) {\n            return consumeFromWebSocket(topic);\n        } else {\n            return consume(topic);\n        }\n    }\n\n    private int consume(String topic) {\n        int numMessagesConsumed = 0;\n        int returnCode = 0;\n","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdConsume.java#L145-L181","documentation":"CmdConsume.run rejects a negative numMessagesToConsume with a CommandLine.ParameterException. The consume command treats 0 as valid (consume nothing / until limit) but a negative count is meaningless, so it fails fast before creating the consumer.","triggerScenarios":"Passing --num-messages -1 (or any negative value) on the consume command line.","commonSituations":"Script computing the count from a counter that can go negative (e.g. total - consumed with underflow); typo'd flag order so a negative number lands in --num-messages; default unset variable evaluated as negative.","solutions":["Pass a non-negative value: --num-messages 0 or a positive count","Clamp the computed value in the calling script (e.g. MAX(0, n))","Check flag ordering/typos so the intended number is actually bound to --num-messages"],"exampleFix":"// before\nNUM=$(($TOTAL - $SENT))   # can be -3\npulsar-client consume ... --num-messages $NUM\n// after\nNUM=$(( TOTAL > SENT ? TOTAL - SENT : 0 ))\npulsar-client consume ... --num-messages $NUM","handlingStrategy":"validation","validationCode":"if [ \"$NUM\" -lt 0 ] 2>/dev/null; then echo \"--num-messages must be >= 0\" >&2; exit 2; fi","typeGuard":"static int clampNonNegative(int n) { return Math.max(0, n); }","tryCatchPattern":"try {\n    int rc = cmdConsume.run();\n} catch (CommandLine.ParameterException e) {\n    if (e.getMessage().contains(\"Number of messages\")) {\n        System.err.println(\"Fix --num-messages: must be zero or positive, got \" + numMessagesArg);\n        System.exit(2);\n    } else { throw e; }\n}","preventionTips":["Clamp computed counts with Math.max(0, n) in scripts before passing them","Don't use negative values as sentinels for 'unlimited' — omit the flag instead","Validate numeric arguments in wrappers (grep -E '^[0-9]+$') before invoking the CLI","Test pipeline scripts with edge inputs (0, negative, empty) so failures surface early"],"tags":["cli","validation","arguments","picocli"],"backgroundTag":"invalid-argument-value","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}