{"record":{"id":"9e9cb73660b99cc8","repo":"apache/pulsar","slug":"failed-to-retrieve-the-state-value-for-key-key","errorCode":null,"errorMessage":"Failed to retrieve the state value for key '${key}'","messagePattern":"Failed to retrieve the state value for key '(.+?)'","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java","lineNumber":200,"sourceCode":"                }\n        );\n    }\n\n    @Override\n    public ByteBuffer get(String key) {\n        try {\n            return result(getAsync(key));\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to retrieve the state value for key '\" + key + \"'\", e);\n        }\n    }\n\n    @Override\n    public StateValue getStateValue(String key) {\n        try {\n            return result(getStateValueAsync(key));\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to retrieve the state value for key '\" + key + \"'\", e);\n        }\n    }\n\n    @Override\n    public CompletableFuture<StateValue> getStateValueAsync(String key) {\n        return table.getKv(Unpooled.wrappedBuffer(key.getBytes(UTF_8))).thenApply(\n                data -> {\n                    try {\n                        if (data != null && data.value() != null && data.value().readableBytes() >= 0) {\n                            byte[] result = new byte[data.value().readableBytes()];\n                            data.value().readBytes(result);\n                            return new StateValue(result, data.version(), data.isNumber());\n                        }\n                        return null;\n                    } finally {\n                        if (data != null) {\n                            ReferenceCountUtil.safeRelease(data);\n                        }","sourceCodeStart":182,"sourceCodeEnd":218,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java#L182-L218","documentation":"BKStateStoreImpl.getStateValue blocks on getStateValueAsync and wraps failures in a RuntimeException with this message, keeping the cause. Same family as get() but for the decoded StateValue path (kv getKv), meaning fetching the raw key/value entry from the BookKeeper-backed state table failed.","triggerScenarios":"Calling getStateValue(key) when table.getKv fails — storage service errors, timeouts, connection problems — or when result() unwraps any exceptionally-completed future.","commonSituations":"Storage cluster degradation; table service restarts; instance reading state during table restore/migration; repeated errors across many keys indicating cluster-wide trouble.","solutions":["Inspect the cause for the exact table/getKv failure.","Check storage cluster and table proxy health before retrying.","Switch to getStateValueAsync with backoff retries for transient faults.","If persistent, re-initialize the state table for the function via the state API."],"exampleFix":"// before\nStateValue v = store.getStateValue(\"key\");\n// after\nStateValue v = store.getStateValueAsync(\"key\")\n    .exceptionally(ex -> {\n        throw new CompletionException(\"state read failed for key\", ex);\n    }).join();","handlingStrategy":"retry","validationCode":"// probe the kv path before bulk reads\nstore.getStateValueAsync(\"__probe__\").get(5, TimeUnit.SECONDS);","typeGuard":null,"tryCatchPattern":"StateValue v = withBackoff(3, () -> {\n    try { return store.getStateValue(key); }\n    catch (RuntimeException e) { if (!isTransient(e.getCause())) throw e; return null; }\n});","preventionTips":["Add backoff retries for transient storage faults.","Avoid reading state during table restore/migration operations.","Alert on cluster-wide state read failures rather than handling per key."],"tags":["state","bookkeeper","read","blocking-call"],"backgroundTag":"state-store-operation-failed","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"}