apache/pulsar · error · IllegalArgumentException

${name} cannot be less than <${min}>!

Error message

${name} cannot be less than <${min}>!

What it means

ValueValidationUtil.minValueCheck rejects a nullable Long parameter smaller than a configured minimum, throwing '<name> cannot be less than <min>!'. It enforces lower bounds on CLI options (e.g. minimum retention, message TTL floors).

Source

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

            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. Raise the parameter value to at least the reported min.
2. Verify units — the min is often expressed in a different unit than you assumed (seconds vs minutes, MB vs bytes).
3. Clamp computed values in scripts before passing them: value < min ? min : value.
4. Consult the tool docs for the minimum allowed value if the bound seems unexpected.

Example fix

// before (min is 60 seconds)
pulsar-admin namespaces set-retention --time 30 ...
// after
pulsar-admin namespaces set-retention --time 60 ...

public static long requireAtLeast(String name, Long value, long min) {
    if (value == null || value < min) {
        throw new IllegalArgumentException(name + " must be >= " + min + ", got " + value);
    }
    return value;
}
// call before the CLI tool: requireAtLeast("retention-time", retentionMinutes, 60);

try {
    tool.run(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("cannot be less than")) {
        System.err.println("Raise the value: " + e.getMessage());
    } else throw e;
}

When it happens

Trigger: Calling minValueCheck(name, value, min) with value < min (value is a Long, so an unboxed comparison) — e.g. --retention-time below the tool's minimum allowed minutes.

Common situations: Passing small time/size values that fall under a documented floor; unit confusion (seconds vs minutes); computed values (now - horizon) going below the minimum.

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
• 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/573314eebb3299da. Report an issue: GitHub.