apache/pulsar · error · IllegalArgumentException

MetadataStoreConfig query parameter '${key}' must be an inte

Error message

MetadataStoreConfig query parameter '${key}' must be an integer

What it means

parseInt() wraps NumberFormatException from Integer.parseInt into IllegalArgumentException 'MetadataStoreConfig query parameter <key> must be an integer'. Thrown when a numeric query parameter in the metadata store URL has a non-numeric value.

Source

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

                    + "' 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

Provide a plain decimal integer with no units or separators.
Use milliseconds for timeout parameters (e.g. 30000, not 30s).
Strip whitespace/quotes from templated values.

Example fix

// before
?sessionTimeoutMillis=30s
// after
?sessionTimeoutMillis=30000

Defensive patterns

Strategy: validation

Validate before calling

try { Integer.parseInt(value); } catch (NumberFormatException e) {
  throw new IllegalArgumentException(key + " must be an integer");
}

Prevention

Never include units (s, ms) in numeric values
Strip quotes/whitespace from templated configs
Sanity-parse all numeric params before startup

When it happens

Trigger: Any integer-typed query parameter given a non-integer value, e.g. ?sessionTimeoutMillis=30s or ?sessionTimeoutMillis=abc.

Common situations: Including time units in values (30s, 500ms) when plain milliseconds are expected; quoted values from YAML leaking into the URL; whitespace or underscore-formatted numbers.

Related errors

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