apache/pulsar · error · IllegalArgumentException

Unsupported MetadataStoreConfig query parameter '${key}'. Su

Error message

Unsupported MetadataStoreConfig query parameter '${key}'. Supported parameters are ${supported}

What it means

MetadataStoreConfigQueryParams.createConfig() maps known query-parameter keys from a metadata store URL (e.g. metadata-store-url?metadataStoreName=...&sessionTimeoutMillis=...) to MetadataStoreConfigBuilder setters. An unknown key that is recognized as a config param domain but has no registered setter throws IllegalArgumentException listing the supported keys.

Source

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

            positiveIntParam("numSerDesThreads", MetadataStoreConfigBuilder::numSerDesThreads),
            positiveIntParam("sessionTimeoutMillis", MetadataStoreConfigBuilder::sessionTimeoutMillis));

    private MetadataStoreConfigQueryParams() {
    }

    static boolean contains(String key) {
        return PARAM_SETTERS.containsKey(key);
    }

    @SuppressWarnings("rawtypes")
    static MetadataStoreConfig createConfig(AbstractConfiguration conf, Map<String, String> configParams) {
        MetadataStoreConfigBuilder builder = MetadataStoreConfig.builder()
                .sessionTimeoutMillis(conf.getZkTimeout())
                .metadataStoreName(MetadataStoreConfig.METADATA_STORE);
        configParams.forEach((key, value) -> {
            BiConsumer<MetadataStoreConfigBuilder, String> setter = PARAM_SETTERS.get(key);
            if (setter == null) {
                throw new IllegalArgumentException("Unsupported MetadataStoreConfig query parameter '" + key
                        + "'. Supported parameters are " + PARAM_SETTERS.keySet());
            }
            setter.accept(builder, value);
        });
        return builder.build();
    }

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

    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(

View on GitHub (pinned to 820761864e)

Solutions

1. Correct the key to one listed in the error message (PARAM_SETTERS keySet: sessionTimeoutMillis, metadataStoreName, etc.).
2. Check the parameter name against the docs for your exact Pulsar version.
3. Remove the unknown parameter if it is obsolete.
4. Put unrecognized (provider-specific) params before the config section or ensure the URL parser routes them to providerParams.

Example fix

// before
metadata-store-url: zk+tls://zk1:2181/my/ledgers?sessionTimoutMillis=30000
// after
metadata-store-url: zk+tls://zk1:2181/my/ledgers?sessionTimeoutMillis=30000

Set<String> supported = Set.of("sessionTimeoutMillis","metadataStoreName");
for (String key : params.keySet()) {
  if (!supported.contains(key)) throw new IllegalArgumentException("unsupported param: " + key);
}

boolean isSupportedParam(String key) { return MetadataStoreConfigQueryParams.contains(key); }

When it happens

Trigger: Passing an unrecognized key=value pair in the MetadataStoreConfig portion of a metadata store URL, e.g. a misspelled key like 'sessionTimoutMillis' or a key not in PARAM_SETTERS.

Common situations: Typos in metadata-store-url query strings; copy-pasting parameters valid in another Pulsar version; documentation drift between versions (a parameter was renamed or removed).

Related errors

• Metadata store address argument is required (--metadata-stor
• configuredService should not be an instance of SystemTopicBa
• Invalid auto split/merge configuration: ${message}
• is not an instance of MetadataStore
• Neither METADATA_STORE_INSTANCE configuration set in the BK

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