apache/pulsar · error · IllegalArgumentException

${paramName} cannot be bigger than <${maxValue}>!

Error message

${paramName} cannot be bigger than <${maxValue}>!

What it means

ValueValidationUtil.maxValueCheck is a CLI argument guard in pulsar-cli-utils: it throws IllegalArgumentException when a numeric parameter exceeds an allowed maximum. It is used by Pulsar admin/client tooling to reject out-of-range option values (e.g. retention size, batch sizes) before they reach the server. The message embeds the parameter name and the max bound.

Source

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

 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * 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");

View on GitHub (pinned to 820761864e)

Solutions

1. Lower the argument value to <= the reported maxValue in the message.
2. Check unit scaling: if the tool expects bytes and you passed a page/kilobyte figure, convert before invoking.
3. Fix the calling script so variables are clamped/validated before building the command line.
4. If the max is legitimately too low for your use case, check documentation/upstream for the current limit rather than patching the util.

Example fix

// before
pulsar-admin topics set-retention --size 100G ...
// after (if the limit is 40GB)
pulsar-admin topics set-retention --size 40G ...

public static void requireMax(String name, long value, long max) {
    if (value > max) {
        throw new IllegalArgumentException(name + "=" + value + " exceeds max " + max);
    }
}
// call before the CLI tool: requireMax("size", parsedSize, 40L * 1024 * 1024 * 1024);

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

When it happens

Trigger: Any CLI/admin call site invoking ValueValidationUtil.maxValueCheck(paramName, value, maxValue) with value > maxValue — e.g. passing --max-messages 100000 when the tool caps it lower.

Common situations: Scripting Pulsar CLI tools with variables that exceed documented limits; typos producing absurd values (extra zero); copy-pasted commands from docs tuned for larger clusters; unit confusion (bytes vs MB).

Related errors

• ${paramName} cannot be less than or equal to <0>!
• ${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/34af5c1b8700c10a. Report an issue: GitHub.