apache/kafka · error · org.apache.kafka.common.errors.TimeoutException

Failed to get offsets by times in {}ms

Error message

Failed to get offsets by times in {}ms

What it means

A re-thrown TimeoutException from offsetsForTimes(timestampsToSearch, timeout) when the underlying ListOffsets request to the broker does not complete within the supplied timeout. The wrapping message reports the elapsed budget in milliseconds to distinguish it from a bare timeout. It indicates the async application-event handler could not deliver offsets for all searched partitions before the deadline.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java:1438

            ListOffsetsEvent listOffsetsEvent = new ListOffsetsEvent(
                    timestampsToSearch,
                    calculateDeadlineMs(time, timeout),
                    true);

            // If timeout is set to zero return empty immediately; otherwise try to get the results
            // and throw timeout exception if it cannot complete in time.
            if (timeout.toMillis() == 0L) {
                applicationEventHandler.add(listOffsetsEvent);
                return listOffsetsEvent.emptyResults();
            }

            try {
                Map<TopicPartition, OffsetAndTimestampInternal> offsets = applicationEventHandler.addAndGet(listOffsetsEvent);
                Map<TopicPartition, OffsetAndTimestamp> results = new HashMap<>(offsets.size());
                offsets.forEach((k, v) -> results.put(k, v != null ? v.buildOffsetAndTimestamp() : null));
                return results;
            } catch (TimeoutException e) {
                throw new TimeoutException("Failed to get offsets by times in " + timeout.toMillis() + "ms");
            }
        } finally {
            release();
        }
    }

    @Override
    public Map<TopicPartition, Long> beginningOffsets(Collection<TopicPartition> partitions) {
        return beginningOffsets(partitions, defaultApiTimeoutMs);
    }

    @Override
    public Map<TopicPartition, Long> beginningOffsets(Collection<TopicPartition> partitions, Duration timeout) {
        return beginningOrEndOffset(partitions, ListOffsetsRequest.EARLIEST_TIMESTAMP, timeout);
    }

    @Override
    public Map<TopicPartition, Long> endOffsets(Collection<TopicPartition> partitions) {

View on GitHub (pinned to c31c9215e1)

Solutions

1. Increase the timeout passed to offsetsForTimes (or raise default.api.timeout.ms) to give the broker time to respond.
2. Check broker health: partition leadership, under-replicated partitions, and broker GC log for the affected topic-partitions.
3. Reduce parallelism of admin-style calls on the same consumer or batch fewer partitions per offsetsForTimes call.
4. If reproducible for specific partitions, verify those partitions have an elected leader via kafka-metadata-shell or admin describeTopics.

Example fix

// before
Map<TopicPartition, OffsetAndTimestamp> r =
    consumer.offsetsForTimes(q, Duration.ofMillis(500)); // throws on slow broker

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

Duration timeout = Duration.ofSeconds(10);
int attempt = 0;
Map<TopicPartition, OffsetAndTimestamp> result;
while (true) {
    try {
        result = consumer.offsetsForTimes(timestampsToSearch, timeout);
        break;
    } catch (TimeoutException e) {
        if (++attempt >= MAX_RETRIES) throw e;
        timeout = timeout.multipliedBy(2); // back off before retrying
    }
}

When it happens

Trigger: Calling consumer.offsetsForTimes(map, Duration.ofMillis(X)) where the broker is slow, unreachable, or has not elected a leader for one of the partitions within X ms; the new consumer's background network thread is starved or blocked; partitions are in an offline/preferred-replica-election in-progress state.

Common situations: Broker GC pauses, controller failover, or partition reassignment making ListOffsets slow; under-provisioned client network threads handling many concurrent admin calls; tight timeouts (sub-second) inherited from request.timeout.ms; reaching this during a rolling broker upgrade.

Related errors

• Operation timed out before completion
• Failed to get offsets by times in {}ms
• Timeout expired while fetching topic metadata
• Timeout of {}ms expired before the position for partition {}
• Timeout of {}ms expired before the last committed offset for

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