apache/pulsar · error · CommandLine.ParameterException

Number of messages should be zero or positive.

Error message

Number of messages should be zero or positive.

What it means

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.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdConsume.java:163

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

    @Spec
    private CommandSpec commandSpec;

    /**
     * Run the consume command.
     *
     * @return 0 for success, < 0 otherwise
     */
    public int run() throws IOException {
        if (this.subscriptionName == null || this.subscriptionName.isEmpty()) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(), "Subscription name is not provided.");
        }
        if (this.numMessagesToConsume < 0) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(),
                    "Number of messages should be zero or positive.");
        }
        if (this.endTimestamp < 0) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(),
                    "end timestamp should be positive.");
        }

        if (this.serviceURL.startsWith("ws")) {
            return consumeFromWebSocket(topic);
        } else {
            return consume(topic);
        }
    }

    private int consume(String topic) {
        int numMessagesConsumed = 0;
        int returnCode = 0;

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a non-negative value: --num-messages 0 or a positive count
2. Clamp the computed value in the calling script (e.g. MAX(0, n))
3. Check flag ordering/typos so the intended number is actually bound to --num-messages

Example fix

// before
NUM=$(($TOTAL - $SENT))   # can be -3
pulsar-client consume ... --num-messages $NUM
// after
NUM=$(( TOTAL > SENT ? TOTAL - SENT : 0 ))
pulsar-client consume ... --num-messages $NUM

if [ "$NUM" -lt 0 ] 2>/dev/null; then echo "--num-messages must be >= 0" >&2; exit 2; fi

static int clampNonNegative(int n) { return Math.max(0, n); }

try {
    int rc = cmdConsume.run();
} catch (CommandLine.ParameterException e) {
    if (e.getMessage().contains("Number of messages")) {
        System.err.println("Fix --num-messages: must be zero or positive, got " + numMessagesArg);
        System.exit(2);
    } else { throw e; }
}

When it happens

Trigger: Passing --num-messages -1 (or any negative value) on the consume command line.

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

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

• Subscription name is not provided.
• Number of times need to be positive number.
• end timestamp should be positive.
• schema type must be 'bytes' or 'auto_consume'
• Please supply message content with either --messages or --fi

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