{"record":{"id":"793f168377ec3735","repo":"apache/pulsar","slug":"number-of-messages-should-be-zero-or-positive-793f16","errorCode":null,"errorMessage":"Number of messages should be zero or positive.","messagePattern":"Number of messages should be zero or positive\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdRead.java","lineNumber":127,"sourceCode":"    @Option(names = { \"-mp\", \"--print-metadata\" }, description = \"Message metadata\")\n    private boolean printMetadata = false;\n\n    public CmdRead() {\n        // Do nothing\n        super();\n    }\n\n    /**\n     * Run the read command.\n     *\n     * @return 0 for success, < 0 otherwise\n     */\n    public int run() throws PulsarClientException, IOException {\n        if (this.numMessagesToRead < 0) {\n            throw (new IllegalArgumentException(\"Number of messages should be zero or positive.\"));\n        }\n        if (!START_LATEST.equals(startMessageId) && !START_EARLIEST.equals(startMessageId)) {\n            throw new IllegalArgumentException(\"--start-message-id must be 'latest' or 'earliest'; the \"\n                    + \"'<ledgerId>:<entryId>' form is not supported by this version of pulsar-client.\");\n        }\n\n        if (this.serviceURL.startsWith(\"ws\")) {\n            return readFromWebSocket(topic);\n        } else {\n            return read(topic);\n        }\n    }\n\n    private int read(String topic) {\n        int numMessagesRead = 0;\n        int returnCode = 0;\n\n        final Schema<?> schema;\n        if (\"auto_consume\".equals(schemaType)) {\n            schema = Schema.autoConsume();\n        } else if (\"bytes\".equals(schemaType)) {","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdRead.java#L109-L145","documentation":"CmdRead.run() validates the --num-messages (-n) option before opening the client. A negative count is meaningless for a reader, so the command throws IllegalArgumentException. Zero is allowed (read nothing).","triggerScenarios":"Running `pulsar-client read <topic> -n -5` (or any negative value), typically from a computed variable or a script bug.","commonSituations":"Scripts computing the count from a diff or config that went negative; inverted option parsing (e.g. passing -5 as an unnamed arg); copying commands with a placeholder like -n N left unfilled and mangled by the shell.","solutions":["Pass a non-negative --num-messages value, e.g. -n 10 (or omit it if a default is acceptable).","Validate/clamp the count in the calling script: MAX(0, count).","Check the script logic that produces the number — a negative value usually indicates an upstream computation error."],"exampleFix":"// before\npulsar-client read my-topic -n $((start-end))   // negative\n// after\npulsar-client read my-topic -n $((end-start))   // ensure >= 0","handlingStrategy":"validation","validationCode":"// bash\nN=${N:-10}; case \"$N\" in ''|*[!0-9]*) echo 'num messages must be >= 0'; exit 1;; esac","typeGuard":"function isNonNegativeInt(n) { return Number.isInteger(n) && n >= 0; }","tryCatchPattern":"try { readCmd(numMessages); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"zero or positive\")) { /* clamp and retry */ } else throw e; }","preventionTips":["Validate counts computed in scripts are non-negative before passing -n.","Don't leave -n placeholders unfilled in command templates.","Prefer explicit positive values over computed expressions where possible."],"tags":["cli","validation","argument","pulsar-client"],"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"}