{"id":"2176ffb7deefd369","repo":"apache/kafka","slug":"operation-timed-out-before-completion-2176ff","errorCode":null,"errorMessage":"Operation timed out before completion","messagePattern":"Operation timed out before completion","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerImpl.java","lineNumber":1382,"sourceCode":"                } else if (!hadEvents) {\n                    // If the above processing yielded no events, then let's sit tight for a bit to allow the\n                    // background thread to either finish the task, or populate the background event\n                    // queue with things to process in our next loop.\n                    Timer pollInterval = time.timer(100L);\n                    log.trace(\"Waiting {} ms for future {} to complete\", pollInterval.remainingMs(), future);\n                    T result = ConsumerUtils.getResult(future, pollInterval);\n                    log.trace(\"Future {} completed successfully\", future);\n                    return result;\n                }\n            } catch (TimeoutException e) {\n                // Ignore this as we will retry the event until the timeout expires.\n            } finally {\n                timer.update();\n            }\n        } while (timer.notExpired());\n\n        log.trace(\"Future {} did not complete within timeout\", future);\n        throw new TimeoutException(\"Operation timed out before completion\");\n    }\n\n    // Visible for testing\n    void completeQuietly(final Utils.ThrowingRunnable function,\n                         final String msg,\n                         final AtomicReference<Throwable> firstException) {\n        try {\n            function.run();\n        } catch (TimeoutException e) {\n            log.debug(\"Timeout expired before the {} operation could complete.\", msg);\n        } catch (Exception e) {\n            firstException.compareAndSet(null, e);\n        }\n    }\n\n    @Override\n    public String clientId() {\n        return clientId;","sourceCodeStart":1364,"sourceCodeEnd":1400,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerImpl.java#L1364-L1400","documentation":"Thrown by ShareConsumerImpl when a background future (fetch, commit, or other share-consumer operation) does not complete before the request timer expires. The share consumer delegates work to an async background thread and polls a loop bounded by a Timer; when timer.notExpired() returns false before the future resolves, the loop exits and raises this TimeoutException. It is the share group equivalent of a poll/commit request that the broker or network never satisfied in time.","triggerScenarios":"Calling KafkaShareConsumer.poll(...), commitAcknowledgements(), or any blocking share-consumer API while the broker is unreachable, slow, or the background network thread is starved. Also triggered when the requested timeout (e.g. default.api.timeout.ms / request.timeout.ms) is shorter than the time the broker needs to acquire and deliver share-group records.","commonSituations":"Broker outage or network partition between client and broker; share-group coordinator under heavy load or rebalancing; request.timeout.ms set too low; DNS resolution stalls; GC pauses on client or broker; running against a broker version that does not yet support share groups (KIP-932), causing the request to hang until timeout.","solutions":["Increase request.timeout.ms and default.api.timeout.ms in the consumer config so the operation has time to complete.","Check broker reachability and share-group coordinator health (kafka-acls, broker logs, NetworkClient errors).","Ensure the broker version supports share groups and the topic is a regular (non-compacted) topic configured for share consumption.","Tune fetch.min.bytes / fetch.max.wait.ms so the broker returns sooner, and verify the background network thread is not blocked by other long-running calls."],"exampleFix":"// before\nprops.put(ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG, 5000);\nconsumer.poll(Duration.ofSeconds(3));\n\n// after\nprops.put(ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG, 30000);\nprops.put(ConsumerConfig.DEFAULT_API_TIMEOUT_MS_CONFIG, 60000);\nconsumer.poll(Duration.ofSeconds(30));","handlingStrategy":"retry","validationCode":"// No pre-check possible; the operation can only fail after the deadline elapses.\n// Tune timeout via consumer config before constructing the consumer:\nProperties props = new Properties();\nprops.put(ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG, 60000); // bump if broker is slow\nprops.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 60000);\n// Pass a generous timeout to the poll/acknowledge call itself:\nconsumer.poll(Duration.ofSeconds(30));","typeGuard":null,"tryCatchPattern":"try {\n    consumer.poll(Duration.ofSeconds(30));\n} catch (org.apache.kafka.common.errors.TimeoutException e) {\n    // Transient: broker slow, no records, or background event not delivered in time.\n    // Safe to retry the same call on the next loop iteration; no state is corrupted.\n    log.debug(\"poll timed out, will retry\", e);\n}","preventionTips":["Size the poll() Duration to your end-to-end latency budget, not to zero.","If using explicit acknowledgement, ensure acks are issued before the share-group acquire-lock timeout expires.","Raise request.timeout.ms / fetch.max.wait.ms if the cluster is loaded, but keep it below session.timeout.ms.","Watch broker latency and partition leadership movement; these starve the background thread and surface as this timeout."],"tags":["share-consumer","timeout","network","kafka-client"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}