Introduction

If you are upgrading a Spring Boot 2.6.4 application and see that setErrorHandler is deprecated, the replacement is setCommonErrorHandler. In practice, the most common implementation you configure there is DefaultErrorHandler.

The reason for the change is API consolidation. Spring Kafka moved away from separate legacy handler types for record and batch listeners and introduced CommonErrorHandler as the unified container-level contract.

What to Replace

Older code often looked like this:

factory.setErrorHandler(myErrorHandler);

In the newer API, the equivalent container-level configuration is:

factory.setCommonErrorHandler(myCommonErrorHandler);

If your old handler logic was retry-oriented, the usual concrete replacement is DefaultErrorHandler.

Typical Replacement with DefaultErrorHandler

Here is a common Spring configuration:

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.kafka.config.ConcurrentKafkaListenerContainerFactory;
4import org.springframework.kafka.core.ConsumerFactory;
5import org.springframework.kafka.listener.DefaultErrorHandler;
6import org.springframework.util.backoff.FixedBackOff;
7
8@Configuration
9public class KafkaConfig {
10
11    @Bean
12    public ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory(
13            ConsumerFactory<String, String> consumerFactory) {
14
15        ConcurrentKafkaListenerContainerFactory<String, String> factory =
16                new ConcurrentKafkaListenerContainerFactory<>();
17        factory.setConsumerFactory(consumerFactory);
18
19        DefaultErrorHandler errorHandler =
20                new DefaultErrorHandler(new FixedBackOff(1000L, 2L));
21
22        factory.setCommonErrorHandler(errorHandler);
23        return factory;
24    }
25}

This configuration retries a failed record with a one-second delay and two retry attempts before recovery logic takes over.

Why CommonErrorHandler Replaced setErrorHandler

The old API had several related handler interfaces, which made configuration harder to reason about. CommonErrorHandler gives the container one main error-handling contract for both record listeners and batch listeners.

That means:

• one container-level entry point instead of separate legacy methods
• clearer support for retries, backoff, and recovery
• a more consistent way to configure listener containers across use cases

This change is about container behavior, not listener-specific business logic. If you need per-listener exception mapping, KafkaListenerErrorHandler is still a different feature and serves a different purpose.

When DefaultErrorHandler Is Enough

DefaultErrorHandler is a good default when you want standard retry and recovery behavior. It can classify exceptions, apply backoff, and work with recoverers such as a dead-letter publishing recoverer.

If your application already has custom behavior based on exception type or record content, you may still create your own CommonErrorHandler implementation. But many upgrades only need a straightforward swap from the deprecated setter to setCommonErrorHandler(new DefaultErrorHandler(...)).

That is why migration is usually more about configuration intent than about syntax. If the old application used the container to retry records, seek offsets, or recover failures, those responsibilities still belong at the container level after the upgrade.

For example, many teams pair DefaultErrorHandler with a recoverer that sends failed records to a dead-letter topic after retries are exhausted. That keeps the listener code focused on business logic while the container manages operational retry policy.

That separation is the main reason the new API is easier to maintain. Retry behavior, backoff, recovery, and offset handling stay in one predictable place instead of leaking into listener methods.

Common Pitfalls

• Replacing setErrorHandler with listener-level errorHandler on @KafkaListener. They are different layers.
• Migrating the method name but not the handler type. The newer setter expects a CommonErrorHandler.
• Forgetting that container-level retry and backoff belong in the factory configuration, not inside the listener method itself.
• Assuming the deprecation is only cosmetic. It reflects a real shift toward the unified CommonErrorHandler API.

Summary

• In Spring Boot 2.6.4 era applications, the replacement for setErrorHandler is setCommonErrorHandler.
• 'DefaultErrorHandler is the most common concrete replacement.'
• The new API unifies container-level handling for both record and batch listeners.
• Listener-specific KafkaListenerErrorHandler is a separate feature and not a drop-in replacement.
• Most migrations are a combination of a setter rename and a handler-type update.