apache/pulsar · error · IllegalArgumentException

${paramName} cannot be less than or equal to <0>!

Error message

${paramName} cannot be less than or equal to <0>!

What it means

ValueValidationUtil.positiveCheck(long) rejects non-positive numeric CLI parameters: any value <= 0 throws IllegalArgumentException with '<param> cannot be less than or equal to <0>!'. Parameters guarded here are expected to be strictly positive (counts, sizes, timeouts), so zero and negatives are both invalid.

Source

Thrown at pulsar-cli-utils/src/main/java/org/apache/pulsar/cli/ValueValidationUtil.java:35

 * under the License.
 */
package org.apache.pulsar.cli;

import lombok.experimental.UtilityClass;
import org.apache.commons.lang3.StringUtils;

@UtilityClass
public class ValueValidationUtil {

    public static void maxValueCheck(String paramName, long value, long maxValue) {
        if (value > maxValue) {
            throw new IllegalArgumentException(paramName + " cannot be bigger than <" + maxValue + ">!");
        }
    }

    public static void positiveCheck(String paramName, long value) {
        if (value <= 0) {
            throw new IllegalArgumentException(paramName + " cannot be less than or equal to <0>!");
        }
    }

    public static void positiveCheck(String paramName, int value) {
        if (value <= 0) {
            throw new IllegalArgumentException(paramName + " cannot be less than or equal to <0>!");
        }
    }

    public static void emptyCheck(String paramName, String value) {
        if (StringUtils.isEmpty(value)) {
            throw new IllegalArgumentException("The value of " + paramName + " can't be empty");
        }
    }

    public static void minValueCheck(String name, Long value, long min) {
        if (value < min) {
            throw new IllegalArgumentException(name + " cannot be less than <" + min + ">!");

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a strictly positive value (> 0) for the named parameter.
2. If 0 was intended as 'unlimited/default', omit the flag or use the tool's documented sentinel instead of 0.
3. Fix the calling script to clamp values: [ "$v" -gt 0 ] || exit before invoking the tool.
4. Check sign errors from computed expressions (e.g. end - start) feeding the argument.

Example fix

// before
pulsar-client produce --num-messages 0 ...
// after
pulsar-client produce --num-messages 10 ...

public static long requirePositive(String name, long value) {
    if (value <= 0) throw new IllegalArgumentException(name + " must be > 0, got " + value);
    return value;
}
// call before the CLI tool: requirePositive("num-messages", numMessages);

try {
    tool.run(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("cannot be less than or equal to <0>")) {
        System.err.println("Value must be positive: " + e.getMessage());
    } else throw e;
}

When it happens

Trigger: Calling positiveCheck(paramName, value) with a long value of 0 or negative — e.g. --rate -1, --messages 0 on a producer/consumer CLI tool.

Common situations: Uninitialized variables in shell scripts defaulting to 0; arithmetic producing negative values; user assuming 0 means 'unlimited' when the tool requires a positive number.

Related errors

• ${paramName} cannot be bigger than <${maxValue}>!
• ${name} cannot be less than <${min}>!
• The value of ${paramName} can't be empty
• byte string cannot be empty
• Number of messages should be zero or positive.

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