apache/pulsar · error · IllegalArgumentException

MetadataStoreConfig query parameter '${key}' must be true or

Error message

MetadataStoreConfig query parameter '${key}' must be true or false

What it means

parseBoolean() validates string values for boolean MetadataStoreConfig query parameters. If the value is neither 'true' nor 'false' (case-insensitive), it throws IllegalArgumentException naming the offending key.

Source

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

    }

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

    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");
        }

View on GitHub (pinned to 820761864e)

Solutions

Change the value to exactly true or false (any case).
Validate all URL query values before starting the broker/bookie.
Check documentation for which parameters are boolean-typed.

Example fix

// before
?allowReadOnlyOps=yes
// after
?allowReadOnlyOps=true

Defensive patterns

Strategy: validation

Validate before calling

if (!"true".equalsIgnoreCase(v) && !"false".equalsIgnoreCase(v))
    throw new IllegalArgumentException(key + " must be true or false");

Prevention

Use only literal true/false in URL query values
Never use yes/no or 1/0 for these params
Validate config values in a pre-startup check

When it happens

Trigger: booleanParam(key, value) called from createConfig() when a boolean query parameter in the metadata store URL has a non-boolean value, e.g. ?allowReadOnlyOps=yes or ?enableDigestTypeVerification=1.

Common situations: Using shell-style or numeric booleans (yes/no, 1/0) in URLs; case-confusion is fine but format confusion is not; hand-edited broker.conf metadataUrl values.

Related errors

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