What causes "Failed to get offsets by times in {}ms" in apache/kafka?

Increase the timeout passed to offsetsForTimes / endOffsets / beginningOffsets (it is the method's Duration argument, not request.timeout.ms).

apache/kafka · error · TimeoutException

Failed to get offsets by times in {}ms

Error message

Failed to get offsets by times in {}ms

What it means

TimeoutException thrown by OffsetFetcher when offsetsForTimes (or listOffsets) cannot complete within the supplied timer. The retry loop polls the network client, awaits metadata updates between attempts, and if timer.notExpired() is false after exhausting attempts, the partial result is discarded and this exception is raised. The elapsed time is included so the caller can correlate against request timeouts.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/OffsetFetcher.java:192

            // if timeout is set to zero, do not try to poll the network client at all
            // and return empty immediately; otherwise try to get the results synchronously
            // and throw timeout exception if it cannot complete in time
            if (timer.timeoutMs() == 0L)
                return result;

            client.poll(future, timer);

            if (!future.isDone()) {
                break;
            } else if (remainingToSearch.isEmpty()) {
                return result;
            } else {
                client.awaitMetadataUpdate(timer);
            }
        } while (timer.notExpired());

        throw new TimeoutException("Failed to get offsets by times in " + timer.elapsedMs() + "ms");
    }

    public Map<TopicPartition, Long> beginningOffsets(Collection<TopicPartition> partitions, Timer timer) {
        return beginningOrEndOffset(partitions, ListOffsetsRequest.EARLIEST_TIMESTAMP, timer, false);
    }

    public Map<TopicPartition, Long> endOffsets(Collection<TopicPartition> partitions, Timer timer) {
        return beginningOrEndOffset(partitions, ListOffsetsRequest.LATEST_TIMESTAMP, timer, false);
    }

    public OptionalLong currentLag(TopicPartition topicPartition) {
        final Long lag = subscriptions.partitionLag(topicPartition, isolationLevel);

        // if the log end offset is not known and hence cannot return lag and there is
        // no in-flight list offset requested yet,
        // issue a list offset request for that partition so that next time
        // we may get the answer; we do not need to wait for the return value
        // since we would not try to poll the network client synchronously

View on GitHub (pinned to c31c9215e1)

Solutions

Increase the timeout passed to offsetsForTimes / endOffsets / beginningOffsets (it is the method's Duration argument, not request.timeout.ms).
Raise request.timeout.ms and retry.backoff.ms so individual ListOffsets attempts do not fail-fast.
Verify cluster health: leader availability for the queried partitions, broker CPU/GC, and network latency with kafka-broker-api-versions.
Reduce the partition batch queried at once if a single slow partition dominates the timer.

Example fix

// before
Map<TopicPartition,OffsetAndTimestamp> r =
    consumer.offsetsForTimes(targets, Duration.ofSeconds(1));

// after
Map<TopicPartition,OffsetAndTimestamp> r =
    consumer.offsetsForTimes(targets, Duration.ofSeconds(30));

Defensive patterns

Strategy: retry

Validate before calling

long requestTimeout = Math.max(timeoutMs, 2 * fetchMetadataTimeoutMs);
if (requestTimeout < 1000L) {
    throw new IllegalArgumentException("offsetsForTimes timeout must allow for a metadata round-trip; got " + requestTimeout);
}

Try / catch

long backoff = 100L;
for (int attempt = 0; attempt < maxAttempts; attempt++) {
    try {
        return consumer.offsetsForTimes(timestampsToSearch, Duration.ofMillis(timeoutMs));
    } catch (org.apache.kafka.common.errors.TimeoutException e) {
        if (attempt == maxAttempts - 1) throw e;
        try { Thread.sleep(backoff); } catch (InterruptedException ie) { Thread.currentThread().interrupt(); throw e; }
        backoff = Math.min(backoff * 2, 5000L);
    }
}

Prevention

Size the timeout to at least the broker's advertised request timeout plus a network round-trip margin.
Ensure the broker(s) for the queried partitions are reachable and not in the middle of a leader election before issuing offsetsForTimes.
Warm up metadata (poll once, or await a metadata refresh) before bulk offsetsForTimes calls on fresh consumers.
When querying many partitions, batch them in a single call rather than N small calls to amortize metadata waits.
In containers with strict CPU throttling, raise the timeout — the consumer's own timer may be expiring under contention.

When it happens

Trigger: Thrown by KafkaConsumer.offsetsForTimes(), beginningOffsets(), or endOffsets() when the underlying ListOffsets requests do not all complete within the timeout passed to those calls. Triggered by slow brokers, leader elections mid-request, or repeated retried errors (e.g. NOT_LEADER_AVAILABLE) exhausting the timer.

Common situations: Broker overload or GC pauses, network latency, request.timeout.ms lower than the offsetsForTimes timeout, frequent leader elections,topic partition movement, or a thin client polling a large partition set. Also seen when the cluster is mid-recovery and metadata is unstable.

Related errors

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