apache/kafka · error · IllegalStateException

Attempt to retrieve value from future which hasn't successfu

Error message

Attempt to retrieve value from future which hasn't successfully completed

What it means

IllegalStateException thrown by RequestFuture.value() when the caller asks for the result before the future has completed successfully. RequestFuture is an internal ad-hoc future used by the consumer's request/response machinery; its value is only meaningful after complete(value) has been called. Calling value() on an incomplete or failed future is a programming error in the consumer internals, not a recoverable network condition.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/RequestFuture.java:74

     * @return true if the response is ready, false otherwise
     */
    public boolean isDone() {
        return result.get() != INCOMPLETE_SENTINEL;
    }

    public boolean awaitDone(long timeout, TimeUnit unit) throws InterruptedException {
        return completedLatch.await(timeout, unit);
    }

    /**
     * Get the value corresponding to this request (only available if the request succeeded)
     * @return the value set in {@link #complete(Object)}
     * @throws IllegalStateException if the future is not complete or failed
     */
    @SuppressWarnings("unchecked")
    public T value() {
        if (!succeeded())
            throw new IllegalStateException("Attempt to retrieve value from future which hasn't successfully completed");
        return (T) result.get();
    }

    /**
     * Check if the request succeeded;
     * @return true if the request completed and was successful
     */
    public boolean succeeded() {
        return isDone() && !failed();
    }

    /**
     * Check if the request failed.
     * @return true if the request completed with a failure
     */
    public boolean failed() {
        return result.get() instanceof RuntimeException;
    }

View on GitHub (pinned to c31c9215e1)

Solutions

If extending consumer internals, always gate value() behind an succeeded() / awaitDone() check.
Upgrade kafka-clients: this usually indicates an internal state-machine bug that has likely been fixed.
Capture the stack trace and report against the Kafka JIRA with the consumer config and broker version.

Example fix

// before
RequestFuture<Foo> f = sendRequest();
Foo v = f.value();

// after
RequestFuture<Foo> f = sendRequest();
if (f.awaitDone(30, TimeUnit.SECONDS) && f.succeeded()) {
    Foo v = f.value();
} else if (f.failed()) {
    throw f.exception();
}

Defensive patterns

Strategy: type-guard

Type guard

// Never call RequestFuture.value() without first narrowing on state.
java.util.function.Predicate<RequestFuture<?>> isUsable =
    f -> f.isDone() && !f.failed();
if (isUsable.test(future)) {
    Object v = future.value();
}
// or, with the public API surface users actually see:
java.util.concurrent.Future<T> f = ...;
if (f.isDone() && !f.isCancelled()) {
    T v = f.get(); // throws ExecutionException for failures instead of IllegalStateException
}

Try / catch

try {
    return future.value();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("hasn't successfully completed")) {
        // programming error — do not retry, fix the call site
        throw new IllegalStateException("Caller bug: accessed RequestFuture value before completion", e);
    }
    throw e;
}

Prevention

Always guard future.value() with future.succeeded() (or isDone() && !failed()) at the call site.
Prefer composing futures via onSuccess/onFailure listeners over blocking then unwrapping; it eliminates the failure mode entirely.
If you must block, use awaitDone(timeout, unit) and then re-check succeeded() before calling value().
Add a unit test that asserts every value() call site in your code is preceded by a succeeded() check.
Treat the IllegalStateException from value() as a programmer error, not a runtime contingency — never catch-and-retry it blindly.

When it happens

Trigger: Raised when value() is invoked while isDone() is false or while failed() is true. Occurs only inside consumer internal code that mishandles the future lifecycle (e.g. reads value before awaiting completion, or after the future was completed exceptionally). User code does not normally hold a RequestFuture reference.

Common situations: Indicates a bug in the consumer internals or in custom code extending AbstractCoordinator / RequestFutureListener that calls value() at the wrong point. Not caused by config or environment. Rarely seen in stock kafka-clients; if observed it warrants a bug report against the version in use.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/1fc18f2f4e30cc0d.json. Report an issue: GitHub.