apache/pulsar · error · IllegalArgumentException

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

Error message

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

What it means

parsePositiveInt() rejects integer values <= 0 for strictly positive MetadataStoreConfig query parameters, throwing IllegalArgumentException 'must be greater than 0'. Unlike parseNonNegativeInt, 0 is not allowed here.

Source

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

            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) {
            throw new IllegalArgumentException("MetadataStoreConfig query parameter '" + key
                    + "' must be an integer", e);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Change the value to an integer >= 1.
2. Remove the parameter to use the default instead of 0.
3. Consult the error's key against PARAM_SETTERS/docs to learn the valid range.

Example fix

// before
?someCacheSize=0
// after
?someCacheSize=1024

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

When it happens

Trigger: positiveIntParam applied to 0 or a negative value from the metadata store URL config section, e.g. a zero timeout or zero cache-size parameter.

Common situations: Setting a parameter to 0 hoping to disable a feature when 0 is invalid for it; generated configs substituting empty strings that parse to 0 elsewhere; misunderstanding the allowed range for that key.

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/21198c0d3f0f52ea. Report an issue: GitHub.