apache/pulsar · error · IllegalArgumentException

MetadataStoreConfig query parameter '${key}' must be greater

Error message

MetadataStoreConfig query parameter '${key}' must be greater than or equal to 0

What it means

parseNonNegativeInt() parses an integer query-parameter value and rejects negative numbers, throwing IllegalArgumentException 'must be greater than or equal to 0'. Used for parameters like sessionTimeoutMillis where a negative value is meaningless.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/MetadataStoreConfigQueryParams.java:90

    private static Map.Entry<String, BiConsumer<MetadataStoreConfigBuilder, String>> positiveIntParam(
            String key, BiConsumer<MetadataStoreConfigBuilder, Integer> setter) {
        return Map.entry(key, (builder, value) -> setter.accept(builder, parsePositiveInt(key, value)));
    }

    private static boolean parseBoolean(String key, String value) {
        if ("true".equalsIgnoreCase(value)) {
            return true;
        } else if ("false".equalsIgnoreCase(value)) {
            return false;
        }
        throw new IllegalArgumentException("MetadataStoreConfig query parameter '" + key
                + "' must be true or false");
    }

    private static int parseNonNegativeInt(String key, String value) {
        int intValue = parseInt(key, value);
        if (intValue < 0) {
            throw new IllegalArgumentException("MetadataStoreConfig query parameter '" + key
                    + "' must be greater than or equal to 0");
        }
        return intValue;
    }

    private static int parsePositiveInt(String key, String value) {
        int intValue = parseInt(key, value);
        if (intValue <= 0) {
            throw new IllegalArgumentException("MetadataStoreConfig query parameter '" + key
                    + "' must be greater than 0");
        }
        return intValue;
    }

    private static int parseInt(String key, String value) {
        try {
            return Integer.parseInt(value);
        } catch (NumberFormatException e) {

View on GitHub (pinned to 820761864e)

Solutions

1. Set the value to 0 or a positive integer.
2. Use the documented default by removing the parameter entirely instead of passing -1.
3. Fix templating/variable substitution that produced the negative number.

Example fix

// before
?sessionTimeoutMillis=-1
// after
?sessionTimeoutMillis=30000

int v = Integer.parseInt(value);
if (v < 0) throw new IllegalArgumentException(key + " must be >= 0");

When it happens

Trigger: nonNegativeIntParam applied to a negative number in the metadata store URL config section, e.g. ?sessionTimeoutMillis=-1.

Common situations: Copy-pasted configs with placeholder -1 meaning 'unset'; templating errors substituting negative defaults; confusion about which params accept 0 vs only positive values.

Related errors

• MetadataStoreConfig query parameter '${key}' must be greater
• MetadataStoreConfig query parameter '${key}' must be true or
• MetadataStoreConfig query parameter '${key}' must be an inte
• Timeout during delete operation
• Timeout during close operation

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