{"record":{"id":"9e2c5a04bcf7659b","repo":"apache/pulsar","slug":"failed-to-retrieve-the-state-value-for-key-s","errorCode":null,"errorMessage":"Failed to retrieve the state value for key '%s'","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":191,"sourceCode":"                            result.position(0);\n                            return result;\n                        }\n                        return null;\n                    } finally {\n                        if (data != null) {\n                            ReferenceCountUtil.safeRelease(data);\n                        }\n                    }\n                }\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) {","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java#L173-L209","documentation":"BKStateStoreImpl.get blocks on getAsync and wraps failures in a RuntimeException with this message, preserving the cause. It means retrieving the raw state value (ByteBuffer) for the key from the BookKeeper-backed state table failed. A missing key is normally an empty/null result, not an error — this indicates an actual storage or transport failure.","triggerScenarios":"Calling get(key) when table.get fails: storage proxy down, request timeout, routing errors, or result() unwrapping a failed CompletableFuture.","commonSituations":"BookKeeper cluster issues; state table for the function deleted or in restoring state; network flakiness between function instance and table service proxy.","solutions":["Check the attached cause for the underlying table error (timeout, NotLeader, connection reset).","Verify state storage cluster health and the table service proxy endpoint.","Prefer getAsync with a retry/backoff handler for transient storage failures.","Confirm the function's state table exists (re-run state initialization if it was dropped)."],"exampleFix":"// before\nByteBuffer v = store.get(\"key\");\n// after\nByteBuffer v = store.getAsync(\"key\").get(30, TimeUnit.SECONDS); // surfaces real cause with timeout bound","handlingStrategy":"try-catch","validationCode":"// verify the state store/table is functional before reads\nstore.getAsync(\"__probe__\").get(5, TimeUnit.SECONDS);","typeGuard":null,"tryCatchPattern":"try {\n    ByteBuffer v = store.get(key);\n} catch (RuntimeException e) {\n    // cause is attached: classify via e.getCause()\n    if (isTransient(e.getCause())) {\n        v = store.getAsync(key).get(30, TimeUnit.SECONDS); // retry path with real timeout\n    } else throw e;\n}","preventionTips":["Attach timeouts when using async equivalents to avoid indefinite blocking.","Monitor the table service proxy from the instance network.","Re-create the state table if it was dropped (state will be lost — back it up if needed)."],"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-14T05:17:10.506Z"}