apache/pulsar · error · IllegalArgumentException

Number of messages should be zero or positive.

Error message

Number of messages should be zero or positive.

What it means

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).

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdRead.java:127

    @Option(names = { "-mp", "--print-metadata" }, description = "Message metadata")
    private boolean printMetadata = false;

    public CmdRead() {
        // Do nothing
        super();
    }

    /**
     * Run the read command.
     *
     * @return 0 for success, < 0 otherwise
     */
    public int run() throws PulsarClientException, IOException {
        if (this.numMessagesToRead < 0) {
            throw (new IllegalArgumentException("Number of messages should be zero or positive."));
        }
        if (!START_LATEST.equals(startMessageId) && !START_EARLIEST.equals(startMessageId)) {
            throw new IllegalArgumentException("--start-message-id must be 'latest' or 'earliest'; the "
                    + "'<ledgerId>:<entryId>' form is not supported by this version of pulsar-client.");
        }

        if (this.serviceURL.startsWith("ws")) {
            return readFromWebSocket(topic);
        } else {
            return read(topic);
        }
    }

    private int read(String topic) {
        int numMessagesRead = 0;
        int returnCode = 0;

        final Schema<?> schema;
        if ("auto_consume".equals(schemaType)) {
            schema = Schema.autoConsume();
        } else if ("bytes".equals(schemaType)) {

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a non-negative --num-messages value, e.g. -n 10 (or omit it if a default is acceptable).
2. Validate/clamp the count in the calling script: MAX(0, count).
3. Check the script logic that produces the number — a negative value usually indicates an upstream computation error.

Example fix

// before
pulsar-client read my-topic -n $((start-end))   // negative
// after
pulsar-client read my-topic -n $((end-start))   // ensure >= 0

// bash
N=${N:-10}; case "$N" in ''|*[!0-9]*) echo 'num messages must be >= 0'; exit 1;; esac

function isNonNegativeInt(n) { return Number.isInteger(n) && n >= 0; }

try { readCmd(numMessages); } catch (IllegalArgumentException e) { if (e.getMessage().contains("zero or positive")) { /* clamp and retry */ } else throw e; }

When it happens

Trigger: Running `pulsar-client read <topic> -n -5` (or any negative value), typically from a computed variable or a script bug.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ${paramName} cannot be bigger than <${maxValue}>!
• ${paramName} cannot be less than or equal to <0>!
• The value of ${paramName} can't be empty
• ${name} cannot be less than <${min}>!
• Please supply message content with either --messages or --fi

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/793f168377ec3735. Report an issue: GitHub.