apache/pulsar · error · RuntimeException

Failed to retrieve the state value for key '%s'

Error message

Failed to retrieve the state value for key '%s'

What it means

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.

Source

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

                            result.position(0);
                            return result;
                        }
                        return null;
                    } finally {
                        if (data != null) {
                            ReferenceCountUtil.safeRelease(data);
                        }
                    }
                }
        );
    }

    @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) {

View on GitHub (pinned to 820761864e)

Solutions

1. Check the attached cause for the underlying table error (timeout, NotLeader, connection reset).
2. Verify state storage cluster health and the table service proxy endpoint.
3. Prefer getAsync with a retry/backoff handler for transient storage failures.
4. Confirm the function's state table exists (re-run state initialization if it was dropped).

Example fix

// before
ByteBuffer v = store.get("key");
// after
ByteBuffer v = store.getAsync("key").get(30, TimeUnit.SECONDS); // surfaces real cause with timeout bound

// verify the state store/table is functional before reads
store.getAsync("__probe__").get(5, TimeUnit.SECONDS);

try {
    ByteBuffer v = store.get(key);
} catch (RuntimeException e) {
    // cause is attached: classify via e.getCause()
    if (isTransient(e.getCause())) {
        v = store.getAsync(key).get(30, TimeUnit.SECONDS); // retry path with real timeout
    } else throw e;
}

When it happens

Trigger: Calling get(key) when table.get fails: storage proxy down, request timeout, routing errors, or result() unwrapping a failed CompletableFuture.

Common situations: BookKeeper cluster issues; state table for the function deleted or in restoring state; network flakiness between function instance and table service proxy.

Related errors

• Failed to retrieve the state value for key '${key}'
• 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/9e2c5a04bcf7659b. Report an issue: GitHub.