Introduction

max.poll.interval.ms is a Kafka consumer setting, so in Spring Kafka you override it the same way you override other Kafka client properties: pass it into the consumer configuration. The important part is not only where to set it, but also understanding why the listener is taking so long that the poll interval needs to change.

What max.poll.interval.ms Controls

Kafka expects each consumer to keep calling poll() often enough to prove that it is still alive and making progress. If message processing takes longer than max.poll.interval.ms, the broker considers that consumer stuck and triggers a rebalance.

That usually shows up as repeated partition revocations, duplicate processing, or commit failures after long-running listener work.

This setting is different from session.timeout.ms. Heartbeats keep the consumer session alive, but max.poll.interval.ms still limits how long your code can go between poll cycles.

Set It Through Spring Kafka Consumer Properties

In Spring Boot, the safest generic approach is to pass the raw Kafka property through the consumer properties map.

1spring:
2  kafka:
3    consumer:
4      group-id: orders
5      properties:
6        max.poll.interval.ms: 600000

That sets the poll interval to ten minutes. It is explicit and works even when a Kafka client property does not have a dedicated convenience field in Boot.

You can do the same programmatically:

1@Bean
2public ConsumerFactory<String, String> consumerFactory() {
3    Map<String, Object> props = new HashMap<>();
4    props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
5    props.put(ConsumerConfig.GROUP_ID_CONFIG, "orders");
6    props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
7    props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
8    props.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 600_000);
9    return new DefaultKafkaConsumerFactory<>(props);
10}

Both forms are valid. Choose one place and keep the configuration centralized.

Increasing the Value Is Not the Whole Fix

If a listener needs more than five minutes regularly, the right fix is often architectural, not just a bigger timeout. Common causes are:

• processing too many records in one poll
• making slow network calls inside the listener thread
• doing large database batches synchronously
• blocking on retries instead of sending work elsewhere

Often you get better behavior by reducing max.poll.records, moving heavy work to another executor, or acknowledging after smaller chunks.

Example of reducing the number of records processed per poll:

1spring:
2  kafka:
3    consumer:
4      properties:
5        max.poll.interval.ms: 600000
6        max.poll.records: 50

That can shorten per-poll work enough that rebalances stop without pushing the interval to an extreme value.

Listener Container Timing Still Matters

Spring Kafka listener containers can add their own pacing behavior, such as idle time between polls. That delay still has to fit within the consumer’s poll-interval budget once actual record processing time is included.

So if you deliberately slow the container down, make sure the total time remains comfortably below the configured interval.

A Practical Tuning Strategy

A reasonable order is:

1. measure how long a batch actually takes to process
2. reduce batch size if the listener is doing too much work per poll
3. move slow downstream work off the poll thread if possible
4. increase max.poll.interval.ms only after the above steps are understood

That sequence prevents the timeout from becoming a bandage for a design problem.

Common Pitfalls

The most common mistake is setting the property in the wrong place. It belongs in Kafka consumer properties, not in an unrelated listener annotation.

Another issue is confusing max.poll.interval.ms with heartbeat-related settings. They solve different failure modes.

A third problem is raising the interval drastically while leaving a slow, overloaded listener unchanged. That delays rebalances but does not improve throughput.

Summary

• Override max.poll.interval.ms through Spring Kafka consumer properties.
• In Spring Boot, spring.kafka.consumer.properties.max.poll.interval.ms is the explicit form.
• The Java equivalent is ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG.
• Tune batch size and listener design before relying only on a larger interval.
• Keep total processing time plus any container delay comfortably below the configured limit.