apache/pulsar · error · ParameterException

Invalid key value pair '${property}', valid format like 'a=b

Error message

Invalid key value pair '${property}', valid format like 'a=b'.

What it means

CmdBase.parseListKeyValueMap parses options that accept repeated key=value entries (e.g. --metadata or bookkeeper enrichment pairs). Each entry must contain an '=' at position > 0 so both a non-empty key and a value exist; otherwise a ParameterException is thrown. This rejects malformed property strings before they reach the broker.

Source

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

            Thread.currentThread().interrupt();
            throw new PulsarAdminException(e);
        } catch (TimeoutException e) {
            throw new PulsarAdminException.TimeoutException(e);
        } catch (ExecutionException e) {
            throw PulsarAdminException.wrap(getApiException(e.getCause()));
        } catch (Exception e) {
            throw PulsarAdminException.wrap(getApiException(e));
        }
    }

    Map<String, String> parseListKeyValueMap(List<String> metadata) {
        Map<String, String> map = null;
        if (metadata != null && !metadata.isEmpty()) {
            map = new HashMap<>();
            for (String property : metadata) {
                int pos = property.indexOf('=');
                if (pos <= 0) {
                    throw new ParameterException(String.format("Invalid key value pair '%s', "
                            + "valid format like 'a=b'.", property));
                }
                map.put(property.substring(0, pos), property.substring(pos + 1));
            }
        }
        return map;
    }

    // Used to register the subcomand.
    protected CommandLine getCommander() {
        return commander;
    }

    protected void addCommand(String name, Object cmd) {
        commander.addSubcommand(name, cmd);
    }

    protected void addCommand(String name, Object cmd, String... aliases) {

View on GitHub (pinned to 820761864e)

Solutions

1. Format each entry as key=value with a non-empty key, e.g. --metadata a=b.
2. Quote entries in the shell so '=' is not stripped: --metadata "a=b".
3. To set an empty value, keep the '=' but note the key must be non-empty: a=.
4. Use key:value style only if the specific option documents it; this parser requires '='.

Example fix

// before
pulsar-admin clusters create c1 --metadata myLabel
// after
pulsar-admin clusters create c1 --metadata myLabel=true

for (String kv : metadata) {
    int pos = kv.indexOf('=');
    if (pos <= 0) {
        throw new IllegalArgumentException("Entry '" + kv + "' must be in key=value form with a non-empty key");
    }
}

try {
    cmd.parseArgs(args);
} catch (ParameterException e) {
    System.err.println("Bad --metadata entry: use key=value, e.g. a=b. " + e.getMessage());
}

When it happens

Trigger: Passing values like 'key' (no '='), '=value' (empty key, '=' at index 0), or whitespace-mangled entries to options parsed by parseListKeyValueMap, such as cluster/topic metadata options.

Common situations: Forgetting the value ('--metadata enabled'), quoting issues where shells strip the '=', or copying formats from other tools that use 'key value' or 'key:value'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Illegal auth action '${action}'. Possible values: ${Arrays.t
• ${paramName} cannot be bigger than <${maxValue}>!
• ${paramName} cannot be less than or equal to <0>!
• The value of ${paramName} can't be empty
• ${name} cannot be less than <${min}>!

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