Introduction

In Kafka, request.timeout.ms controls how long the client waits for a broker response before treating the request as timed out. In Spring Boot and Spring Kafka, the right property path depends on which client you want to configure. For a producer setting, the usual location is under the producer-specific properties map rather than at the top level of the Spring configuration.

The Producer-Specific Property Path

If you want to configure the producer's request.timeout.ms, use this in application.properties:

1spring.kafka.bootstrap-servers=localhost:9092
2spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
3spring.kafka.producer.value-serializer=org.apache.kafka.common.serialization.StringSerializer
4spring.kafka.producer.properties.request.timeout.ms=20000

The last line is the important one. It tells Spring Boot to pass the raw Kafka producer property through to the underlying producer configuration.

The same setting in YAML looks like this:

1spring:
2  kafka:
3    bootstrap-servers: localhost:9092
4    producer:
5      key-serializer: org.apache.kafka.common.serialization.StringSerializer
6      value-serializer: org.apache.kafka.common.serialization.StringSerializer
7      properties:
8        request.timeout.ms: 20000

Why the properties Map Matters

Spring Boot has dedicated top-level keys for many common Kafka settings, but not every Kafka client property gets its own Boot-specific shortcut.

For any raw Kafka producer property that Spring does not expose directly, the general pattern is:

• 'spring.kafka.producer.properties.<kafka-property>=value'

That rule works for many producer options beyond request.timeout.ms.

This is why spring.kafka.producer.request.timeout.ms is usually not the right path. The Kafka property needs to go through the producer properties map.

Use the Generic Client Properties Only When Appropriate

Spring also supports a broader pass-through map:

spring.kafka.properties.request.timeout.ms=20000

That sends the property to Kafka clients more generally. For a producer-only timeout, the producer-specific form is usually clearer because it documents intent and avoids surprising interactions with other client types.

A practical rule is:

• use spring.kafka.producer.properties.* for producer-only settings
• use spring.kafka.consumer.properties.* for consumer-only settings
• use spring.kafka.properties.* only when the setting is meant to apply more broadly

What request.timeout.ms Actually Influences

request.timeout.ms is the maximum time the client waits for a broker response to a request. For producers, that interacts with retries, delivery behavior, and the time it takes to surface network or broker problems.

If the timeout is too low:

• transient latency spikes may look like failures
• retries may happen more often than necessary

If the timeout is too high:

• real broker problems may take longer to surface
• application-level failure detection becomes slower

This means the best value depends on network conditions, broker load, and how quickly the application needs to react to trouble.

Example with a Producer Bean

You normally do not need extra Java config if the Spring properties are correct, but it can help to see the equivalent producer factory setup:

1import java.util.HashMap;
2import java.util.Map;
3import org.apache.kafka.clients.producer.ProducerConfig;
4import org.apache.kafka.common.serialization.StringSerializer;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.Configuration;
7import org.springframework.kafka.core.DefaultKafkaProducerFactory;
8import org.springframework.kafka.core.KafkaTemplate;
9import org.springframework.kafka.core.ProducerFactory;
10
11@Configuration
12public class KafkaProducerConfiguration {
13
14    @Bean
15    public ProducerFactory<String, String> producerFactory() {
16        Map<String, Object> props = new HashMap<>();
17        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
18        props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
19        props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
20        props.put(ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, 20000);
21        return new DefaultKafkaProducerFactory<>(props);
22    }
23
24    @Bean
25    public KafkaTemplate<String, String> kafkaTemplate() {
26        return new KafkaTemplate<>(producerFactory());
27    }
28}

This Java version shows the same underlying Kafka property name. Spring Boot properties are simply a cleaner externalized way to express it.

Related Timeout Settings

request.timeout.ms is not the only timeout in play. Depending on the problem you are tuning, you may also need to think about:

• delivery timeout
• retry backoff
• connection setup timing
• consumer polling or session timeouts, if you are tuning consumers instead of producers

That is why timeout tuning should be done in context rather than by changing one number in isolation.

Common Pitfalls

One common mistake is using the wrong Spring property path, such as omitting the producer properties map.

Another mistake is setting the generic spring.kafka.properties.request.timeout.ms when the intent is clearly producer-only. That can make the configuration less explicit.

Developers also sometimes tune request.timeout.ms without considering related producer settings such as retries and delivery timing. Timeout behavior is rarely controlled by one property alone.

Finally, do not assume a timeout problem is always solved by increasing the timeout. Sometimes the real issue is broker reachability, SSL setup, or authentication failure rather than slow responses.

Summary

• In Spring Boot, define the producer timeout as spring.kafka.producer.properties.request.timeout.ms.
• The YAML equivalent goes under spring.kafka.producer.properties.
• Use the producer-specific path when the setting is meant only for producers.
• 'request.timeout.ms controls how long the Kafka client waits for a broker response.'
• Tune it alongside related retry and delivery settings, not in isolation.