{"record":{"id":"8578b6be8f8bf901","repo":"apache/pulsar","slug":"failed-to-increment-key-s-by-amount-s","errorCode":null,"errorMessage":"Failed to increment key '%s' by amount '%s'","messagePattern":"Failed to increment key '(.+?)' by amount '(.+?)'","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java","lineNumber":98,"sourceCode":"    @Override\n    public void close() {\n        table.close();\n    }\n\n    @Override\n    public CompletableFuture<Void> incrCounterAsync(String key, long amount) {\n        // TODO: this can be optimized with a batch operation.\n        return table.increment(\n            Unpooled.wrappedBuffer(key.getBytes(UTF_8)),\n            amount);\n    }\n\n    @Override\n    public void incrCounter(String key, long amount) {\n        try {\n            result(incrCounterAsync(key, amount));\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to increment key '\" + key + \"' by amount '\" + amount + \"'\", e);\n        }\n    }\n\n    @Override\n    public CompletableFuture<Long> getCounterAsync(String key) {\n        return table.getNumber(Unpooled.wrappedBuffer(key.getBytes(UTF_8)));\n    }\n\n    @Override\n    public long getCounter(String key) {\n        try {\n            return result(getCounterAsync(key));\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to retrieve counter from key '\" + key + \"'\");\n        }\n    }\n\n    @Override","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java#L80-L116","documentation":"BKStateStoreImpl.incrCounter blocks on the async increment via result(incrCounterAsync) and wraps any failure in a RuntimeException carrying the key and amount. It indicates the state-table increment against BookKeeper-backed state storage failed, e.g. due to table service errors, timeouts, or invalid input.","triggerScenarios":"Calling incrCounter(key, amount) when the underlying table incr fails: state table not yet created, storage service unreachable, timeout, or null/invalid key handling in the table service.","commonSituations":"BookKeeper storage cluster degraded or table service proxy down; function state configured but state table creation failed; network partition between function instance and storage.","solutions":["Check the cause exception for the underlying table/BookKeeper error (timeout, NotFound, connection refused).","Verify the state table exists for the function (tenant/namespace/name) and was initialized successfully.","Check BookKeeper storage cluster health and the table service (proxy) availability.","Retry the increment; incrCounter is a read-modify-write at the table layer, ensure retries are idempotent for your use case."],"exampleFix":"// before\nstore.incrCounter(\"hits\", 1); // throws raw RuntimeException on any table failure\n// after\ntry {\n    store.incrCounter(\"hits\", 1);\n} catch (RuntimeException e) {\n    log.error(\"counter incr failed, will retry\", e);\n    retryIncr(\"hits\", 1);\n}","handlingStrategy":"retry","validationCode":"// before using state\nStateStore store = context.getStateStore(stateName); // ensure initialized\n// check table reachable via a cheap read\nstore.getCounter(\"__health__\"); // throws early if storage is down","typeGuard":null,"tryCatchPattern":"try {\n    store.incrCounter(key, amount);\n} catch (RuntimeException e) {\n    // transient table-service failure: retry with backoff\n    backoffRetry(() -> store.incrCounter(key, amount), 3);\n}","preventionTips":["Confirm state is enabled and the state table initializes cleanly at instance start.","Monitor BookKeeper storage cluster health before relying on state.","Design counter usage to tolerate re-execution (increments may be retried)."],"tags":["state","bookkeeper","counter","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"}