{"record":{"id":"8a0a697de3ff20fb","repo":"apache/pulsar","slug":"failed-to-update-the-state-value-for-key-s","errorCode":null,"errorMessage":"Failed to update the state value for key '%s'","messagePattern":"Failed to update 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":139,"sourceCode":"            // to create a ByteBuffer to store to the state store\n            // the position of the buffer will be at the end and nothing will be written to table service\n            value.position(0);\n            return table.put(\n                    Unpooled.wrappedBuffer(key.getBytes(UTF_8)),\n                    Unpooled.wrappedBuffer(value));\n        } else {\n            return table.put(\n                    Unpooled.wrappedBuffer(key.getBytes(UTF_8)),\n                    null);\n        }\n    }\n\n    @Override\n    public void put(String key, ByteBuffer value) {\n        try {\n            result(putAsync(key, value));\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to update the state value for key '\" + key + \"'\");\n        }\n    }\n\n    @Override\n    public CompletableFuture<Void> deleteAsync(String key) {\n        return table.delete(\n                Unpooled.wrappedBuffer(key.getBytes(UTF_8)),\n                Options.delete()\n        ).thenApply(ignored -> null);\n    }\n\n    @Override\n    public void delete(String key) {\n        try {\n            result(deleteAsync(key));\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to delete the state value for key '\" + key + \"'\");\n        }","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java#L121-L157","documentation":"BKStateStoreImpl.put blocks on putAsync and wraps failures in a RuntimeException with this message (cause again omitted from the message chain). It means a synchronous state-value write into the BookKeeper-backed state table failed after the future completed exceptionally.","triggerScenarios":"Calling put(key, value) when the table put fails: storage service down, request timeout, table in bad state, or a null value path behaving differently than expected (null values are not written via the table here).","commonSituations":"Oversized state values exceeding server limits; BookKeeper write failures (disk full, quorum loss); function state table corruption; network issues between instance and storage proxy.","solutions":["Inspect logs/table-layer errors for the underlying cause (timeout, storage failure).","Use putAsync to obtain the actual exception from the failed future.","Check value size against the state server limits and shrink or compress the value.","Verify BookKeeper storage health (disk space, bookie availability)."],"exampleFix":"// before\nstore.put(\"key\", value); // throws without cause detail\n// after\nstore.putAsync(\"key\", value)\n    .exceptionally(ex -> {\n        log.error(\"put failed for key\", ex);\n        return null;\n    }).join();","handlingStrategy":"validation","validationCode":"// before putting state\nif (key == null || key.isEmpty()) throw new IllegalArgumentException(\"state key required\");\nint maxStateValueBytes = 1_000_000; // align with server limits\nif (value != null && value.remaining() > maxStateValueBytes) {\n    throw new IllegalArgumentException(\"state value too large: \" + value.remaining());\n}","typeGuard":null,"tryCatchPattern":"try {\n    store.put(key, value);\n} catch (RuntimeException e) {\n    if (isTransient(e)) backoffRetry(() -> store.put(key, value), 3);\n    else throw e;\n}","preventionTips":["Keep state values within server size limits; offload large blobs to object storage.","Use putAsync in async contexts to avoid blocking threads and losing cause detail.","Watch disk usage on bookies — full disks fail writes cluster-wide."],"tags":["state","bookkeeper","write","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"}