apache/pulsar · error · ParameterException

Unknown auto failover policy params specified :

Error message

Unknown auto failover policy params specified : 

What it means

Thrown when the keys of the --auto-failover-policy-params map contain entries the chosen policy type does not recognize. For policy type minAvailable, only 'min_limit' and 'usage_threshold' are accepted; any other key (or missing required keys, depending on flow) marks the params as unknown and raises this ParameterException.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdNamespaceIsolationPolicy.java:239

                .build());

        // validation if necessary
        if (policyType == AutoFailoverPolicyType.min_available) {
            // ignore
            boolean error = true;
            String[] expectParamKeys = { "min_limit", "usage_threshold" };

            if (autoFailoverPolicyParams.size() == expectParamKeys.length) {
                for (String paramKey : expectParamKeys) {
                    if (!autoFailoverPolicyParams.containsKey(paramKey)) {
                        break;
                    }
                }
                error = false;
            }

            if (error) {
                throw new ParameterException(
                        "Unknown auto failover policy params specified : " + autoFailoverPolicyParams);
            }

        } else {
            // either we don't handle the new type or user has specified a bad type
            throw new ParameterException("Unknown auto failover policy type specified : " + autoFailoverPolicyTypeName);
        }

        nsIsolationDataBuilder.unloadScope(unload);

        return nsIsolationDataBuilder.build();
    }

    public CmdNamespaceIsolationPolicy(Supplier<PulsarAdmin> admin) {
        super("ns-isolation-policy", admin);
        addCommand("set", new SetPolicy());
        addCommand("get", new GetPolicy());
        addCommand("list", new GetAllPolicies());

View on GitHub (pinned to 820761864e)

Solutions

1. Use exactly min_limit and usage_threshold for the minAvailable policy, e.g. --auto-failover-policy-params min_limit=10,usage_threshold=80
2. Fix key spelling to match the accepted names
3. Remove any extra/unknown keys from the params list
4. Check the docs for the Pulsar version in use, since accepted param keys can differ between versions

Example fix

// before
--auto-failover-policy-type minAvailable --auto-failover-policy-params minLimit=10,usageThreshold=80
// after
--auto-failover-policy-type minAvailable --auto-failover-policy-params min_limit=10,usage_threshold=80

# check param keys before invoking
ALLOWED="min_limit usage_threshold"
for kv in ${AUTO_FAILOVER_PARAMS//,/ }; do key=${kv%%=*}; [[ " $ALLOWED " == *" $key "* ]] || { echo "bad param key: $key"; exit 1; }; done

try { ... } catch (ParameterException e) { /* unknown param key: correct keys, no retry */ }

When it happens

Trigger: Running `pulsar-admin namespaces-isolation-policy create` with --auto-failover-policy-type minAvailable and --auto-failover-policy-params containing misspelled keys such as minLimit=5 or min-limit=5 (instead of min_limit=5), or extra unknown keys.

Common situations: Camel-case vs snake_case confusion (minLimit vs min_limit); copying params from a different policy type; typos like usage_treshold; adding options from newer/older Pulsar docs than the installed version.

Related errors

• Unknown auto failover policy type specified :
• Need to provide a persistent topic name
• Need to provide a non-persistent topic name
• Invalid message id (must be in format: ledgerId:entryId) val
• unable to parse namespaces parameter list:

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