{"id":"e3be3d614bb0a91d","repo":"apache/kafka","slug":"failed-to-get-offsets-by-times-in-ms","errorCode":null,"errorMessage":"Failed to get offsets by times in {}ms","messagePattern":"Failed to get offsets by times in (.+?)ms","errorType":"exception","errorClass":"org.apache.kafka.common.errors.TimeoutException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java","lineNumber":1438,"sourceCode":"            ListOffsetsEvent listOffsetsEvent = new ListOffsetsEvent(\n                    timestampsToSearch,\n                    calculateDeadlineMs(time, timeout),\n                    true);\n\n            // If timeout is set to zero return empty immediately; otherwise try to get the results\n            // and throw timeout exception if it cannot complete in time.\n            if (timeout.toMillis() == 0L) {\n                applicationEventHandler.add(listOffsetsEvent);\n                return listOffsetsEvent.emptyResults();\n            }\n\n            try {\n                Map<TopicPartition, OffsetAndTimestampInternal> offsets = applicationEventHandler.addAndGet(listOffsetsEvent);\n                Map<TopicPartition, OffsetAndTimestamp> results = new HashMap<>(offsets.size());\n                offsets.forEach((k, v) -> results.put(k, v != null ? v.buildOffsetAndTimestamp() : null));\n                return results;\n            } catch (TimeoutException e) {\n                throw new TimeoutException(\"Failed to get offsets by times in \" + timeout.toMillis() + \"ms\");\n            }\n        } finally {\n            release();\n        }\n    }\n\n    @Override\n    public Map<TopicPartition, Long> beginningOffsets(Collection<TopicPartition> partitions) {\n        return beginningOffsets(partitions, defaultApiTimeoutMs);\n    }\n\n    @Override\n    public Map<TopicPartition, Long> beginningOffsets(Collection<TopicPartition> partitions, Duration timeout) {\n        return beginningOrEndOffset(partitions, ListOffsetsRequest.EARLIEST_TIMESTAMP, timeout);\n    }\n\n    @Override\n    public Map<TopicPartition, Long> endOffsets(Collection<TopicPartition> partitions) {","sourceCodeStart":1420,"sourceCodeEnd":1456,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java#L1420-L1456","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the timeout passed to offsetsForTimes (or raise default.api.timeout.ms) to give the broker time to respond.","Check broker health: partition leadership, under-replicated partitions, and broker GC log for the affected topic-partitions.","Reduce parallelism of admin-style calls on the same consumer or batch fewer partitions per offsetsForTimes call.","If reproducible for specific partitions, verify those partitions have an elected leader via kafka-metadata-shell or admin describeTopics."],"exampleFix":"// before\nMap<TopicPartition, OffsetAndTimestamp> r =\n    consumer.offsetsForTimes(q, Duration.ofMillis(500)); // throws on slow broker\n\n// after\nMap<TopicPartition, OffsetAndTimestamp> r =\n    consumer.offsetsForTimes(q, Duration.ofSeconds(30));","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"Duration timeout = Duration.ofSeconds(10);\nint attempt = 0;\nMap<TopicPartition, OffsetAndTimestamp> result;\nwhile (true) {\n    try {\n        result = consumer.offsetsForTimes(timestampsToSearch, timeout);\n        break;\n    } catch (TimeoutException e) {\n        if (++attempt >= MAX_RETRIES) throw e;\n        timeout = timeout.multipliedBy(2); // back off before retrying\n    }\n}","preventionTips":["This TimeoutException is transient (broker slow, metadata fetch, network) — retry with an exponentially growing timeout.","Cap retries and surface the final exception so callers do not loop forever against an unreachable cluster.","Increase request.timeout.ms / default.api.timeout.ms if offsetsForTimes consistently times out under load.","Distinguish this runtime timeout from the timeout==0 short-circuit in the same method."],"tags":["kafka","consumer","offsets","timeout","network"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}