apache/pulsar · error · RuntimeException

Failed to retrieve the state value for key '${key}'

Error message

Failed to retrieve the state value for key '${key}'

What it means

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.

Source

Thrown at pulsar-functions/instance/src/main/java/org/apache/pulsar/functions/instance/state/BKStateStoreImpl.java:200

                }
        );
    }

    @Override
    public ByteBuffer get(String key) {
        try {
            return result(getAsync(key));
        } catch (Exception e) {
            throw new RuntimeException("Failed to retrieve the state value for key '" + key + "'", e);
        }
    }

    @Override
    public StateValue getStateValue(String key) {
        try {
            return result(getStateValueAsync(key));
        } catch (Exception e) {
            throw new RuntimeException("Failed to retrieve the state value for key '" + key + "'", e);
        }
    }

    @Override
    public CompletableFuture<StateValue> getStateValueAsync(String key) {
        return table.getKv(Unpooled.wrappedBuffer(key.getBytes(UTF_8))).thenApply(
                data -> {
                    try {
                        if (data != null && data.value() != null && data.value().readableBytes() >= 0) {
                            byte[] result = new byte[data.value().readableBytes()];
                            data.value().readBytes(result);
                            return new StateValue(result, data.version(), data.isNumber());
                        }
                        return null;
                    } finally {
                        if (data != null) {
                            ReferenceCountUtil.safeRelease(data);
                        }

View on GitHub (pinned to 820761864e)

Solutions

1. Inspect the cause for the exact table/getKv failure.
2. Check storage cluster and table proxy health before retrying.
3. Switch to getStateValueAsync with backoff retries for transient faults.
4. If persistent, re-initialize the state table for the function via the state API.

Example fix

// before
StateValue v = store.getStateValue("key");
// after
StateValue v = store.getStateValueAsync("key")
    .exceptionally(ex -> {
        throw new CompletionException("state read failed for key", ex);
    }).join();

// probe the kv path before bulk reads
store.getStateValueAsync("__probe__").get(5, TimeUnit.SECONDS);

StateValue v = withBackoff(3, () -> {
    try { return store.getStateValue(key); }
    catch (RuntimeException e) { if (!isTransient(e.getCause())) throw e; return null; }
});

When it happens

Trigger: Calling getStateValue(key) when table.getKv fails — storage service errors, timeouts, connection problems — or when result() unwraps any exceptionally-completed future.

Common situations: Storage cluster degradation; table service restarts; instance reading state during table restore/migration; repeated errors across many keys indicating cluster-wide trouble.

Related errors

• Failed to retrieve the state value for key '%s'
• Failed to increment key '%s' by amount '%s'
• Failed to retrieve counter from key '%s'
• Failed to update the state value for key '%s'
• Failed to delete the state value for key '%s'

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/9e9cb73660b99cc8. Report an issue: GitHub.