{"record":{"id":"685de5534940f021","repo":"apache/pulsar","slug":"state-key-needs-to-be-specified","errorCode":null,"errorMessage":"State key needs to be specified","messagePattern":"State key needs to be specified","errorType":"validation","errorClass":"ParameterException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java","lineNumber":1074,"sourceCode":"        void runCmd() throws Exception {\n            print(getAdmin().functions().getFunctions(tenant, namespace));\n        }\n    }\n\n    @Command(description = \"Fetch the current state associated with a Pulsar Function\")\n    class StateGetter extends FunctionCommand {\n\n        @Option(names = {\"-k\", \"--key\"}, description = \"Key name of State\")\n        private String key = null;\n\n        @Option(names = {\"-w\", \"--watch\"}, description = \"Watch for changes in the value associated with a key \"\n                + \"for a Pulsar Function\")\n        private boolean watch = false;\n\n        @Override\n        void runCmd() throws Exception {\n            if (isBlank(key)) {\n                throw new ParameterException(\"State key needs to be specified\");\n            }\n            do {\n                try {\n                    FunctionState functionState = getAdmin().functions()\n                                                       .getFunctionState(tenant, namespace, functionName, key);\n                    Gson gson = new GsonBuilder().setPrettyPrinting().create();\n                    System.out.println(gson.toJson(functionState));\n                } catch (PulsarAdminException pae) {\n                    if (pae.getStatusCode() == 404 && watch) {\n                        System.err.println(pae.getMessage());\n                    } else {\n                        throw pae;\n                    }\n                }\n                if (watch) {\n                    Thread.sleep(1000);\n                }\n            } while (watch);","sourceCodeStart":1056,"sourceCodeEnd":1092,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java#L1056-L1092","documentation":"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.","triggerScenarios":"Running `pulsar-admin functions state <tenant> <namespace> <functionName>` without --key (or with an empty value), checked at CmdFunctions.java:1074 before calling functions().getFunctionState.","commonSituations":"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.","solutions":["Add --key <stateKey> naming the state entry to fetch","Verify the key was actually set in your script (quote it: --key \"mykey\")","List/inspect the function to confirm which state keys exist"],"exampleFix":"// before\npulsar-admin functions state t n myfunc\n// after\npulsar-admin functions state t n myfunc --key counter","handlingStrategy":"validation","validationCode":"if (key == null || key.isBlank()) {\n    throw new IllegalArgumentException(\"--key must be provided for functions state\");\n}","typeGuard":null,"tryCatchPattern":"try { admin.functions().getFunctionState(tenant, ns, fn, key); }\ncatch (ParameterException e) { if (e.getMessage().equals(\"State key needs to be specified\")) { log.error(\"Provide --key <stateKey>\"); } throw e; }","preventionTips":["Quote --key values in shell scripts so they are not dropped","Remember `functions state` fetches one key per call, not all state","Confirm the state key name with the function developer"],"tags":["cli","validation","state","pulsar-functions"],"backgroundTag":"missing-required-argument","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}