max.poll.interval.ms
max.poll.interval.ms is a Kafka consumer configuration that sets the maximum time between two consecutive poll() calls before the broker considers the consumer dead and triggers a group rebalance. The default value is 300,000 ms (5 minutes). It is independent of session.timeout.ms (which governs heartbeat-based liveness detection) — a consumer can be sending heartbeats normally but still be evicted for violating max.poll.interval.ms if its processing loop is too slow.
Formula
Common violation: processingTimeMs × maxPollRecords > max.poll.interval.ms. With processingTimeMs=1000ms and max.poll.records=500 (default), each poll batch requires 500 seconds of processing — far exceeding the 300-second default.Why it matters in practice
This is one of the most frequently misunderstood Kafka configurations and a common cause of production rebalance loops. The consumer appears healthy in application logs (heartbeat thread is running, no exceptions), but Kafka repeatedly evicts it and triggers rebalances because the poll loop is too slow. The symptom is a consumer that keeps rejoining the group and immediately being evicted, causing continuous rebalance events and growing consumer lag. Fix: either increase max.poll.interval.ms to accommodate worst-case processing time, or reduce max.poll.records so each batch completes faster.
Common mistakes
- •Confusing max.poll.interval.ms with session.timeout.ms — heartbeats are handled by a background thread and do not reflect poll loop activity.
- •Setting max.poll.interval.ms to a very high value (hours) as a workaround — this delays detection of genuinely crashed consumers, causing long rebalances during actual failures.
- •Not monitoring poll.idle.ratio JMX metric — a low value indicates the consumer is spending most of its time processing rather than polling, increasing the risk of exceeding the interval.