apache/pulsar · error · ParameterException

State key needs to be specified

Error message

State key needs to be specified

What it means

Thrown by the `functions state` (querier) subcommand when the --key option is blank. Function state is stored as key/value pairs per function, so a key is required to fetch (or watch) a specific state entry.

Source

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

        void runCmd() throws Exception {
            print(getAdmin().functions().getFunctions(tenant, namespace));
        }
    }

    @Command(description = "Fetch the current state associated with a Pulsar Function")
    class StateGetter extends FunctionCommand {

        @Option(names = {"-k", "--key"}, description = "Key name of State")
        private String key = null;

        @Option(names = {"-w", "--watch"}, description = "Watch for changes in the value associated with a key "
                + "for a Pulsar Function")
        private boolean watch = false;

        @Override
        void runCmd() throws Exception {
            if (isBlank(key)) {
                throw new ParameterException("State key needs to be specified");
            }
            do {
                try {
                    FunctionState functionState = getAdmin().functions()
                                                       .getFunctionState(tenant, namespace, functionName, key);
                    Gson gson = new GsonBuilder().setPrettyPrinting().create();
                    System.out.println(gson.toJson(functionState));
                } catch (PulsarAdminException pae) {
                    if (pae.getStatusCode() == 404 && watch) {
                        System.err.println(pae.getMessage());
                    } else {
                        throw pae;
                    }
                }
                if (watch) {
                    Thread.sleep(1000);
                }
            } while (watch);

View on GitHub (pinned to 820761864e)

Solutions

1. Add --key <stateKey> naming the state entry to fetch
2. Verify the key was actually set in your script (quote it: --key "mykey")
3. List/inspect the function to confirm which state keys exist

Example fix

// before
pulsar-admin functions state t n myfunc
// after
pulsar-admin functions state t n myfunc --key counter

if (key == null || key.isBlank()) {
    throw new IllegalArgumentException("--key must be provided for functions state");
}

try { admin.functions().getFunctionState(tenant, ns, fn, key); }
catch (ParameterException e) { if (e.getMessage().equals("State key needs to be specified")) { log.error("Provide --key <stateKey>"); } throw e; }

When it happens

Trigger: Running `pulsar-admin functions state <tenant> <namespace> <functionName>` without --key (or with an empty value), checked at CmdFunctions.java:1074 before calling functions().getFunctionState.

Common situations: Omitting --key assuming the command dumps all state (it does not); quoting issues causing the key value to be dropped in shell scripts; copy-pasting an example command without replacing the key placeholder.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Either a Java jar or a Python file or a Go executable binary
• Either a Java jar or a Python file or a Go executable binary
• Function Name not provided
• Either a trigger value or a trigger filepath needs to be spe
• --source-file needs to be specified

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