This version is still in development and is not considered stable yet. For the latest stable version, please use Spring for Apache Kafka 4.0.5!

What’s new?

What’s New in 4.1 Since 4.0

This section covers the changes made from version 4.0 to version 4.1. For changes in earlier versions, see Change History.

@KafkaListener Changes

The @KafkaListener annotation now supports an ackMode attribute, allowing individual listeners to override the container factory’s default acknowledgment mode without creating separate container factory beans. The attribute also supports SpEL expressions and property placeholders. See @KafkaListener Annotation for more information.

Share Consumer Acknowledgment Modes

The boolean setExplicitShareAcknowledgment(boolean) property on ContainerProperties has been replaced by the ShareAckMode enum (EXPLICIT, MANUAL, IMPLICIT). The deprecated method still works: true maps to MANUAL, false maps to EXPLICIT. Default behavior is unchanged — applications using the default require no migration. See Record Acknowledgment for mode descriptions and Migration from 4.0 for upgrade details.

Share Consumer Async Commits

A new syncShareCommits property on ContainerProperties controls whether the share container uses commitSync() (default) or commitAsync() for acknowledgment commits. Set to false for higher throughput when slight ack-durability lag is acceptable. See Synchronous vs Asynchronous Commits for details.

Share Consumer Error Handling

Share consumer containers now provide configurable error handling:

  • Poll-level: RecordDeserializationException and CorruptRecordException from poll() are caught so the consumer thread continues; undeserializable records are REJECTed and the next poll proceeds.

  • Listener-level: A ShareConsumerRecordRecoverer interface decides whether to ACCEPT, RELEASE, or REJECT when the listener throws. The default is ShareConsumerRecordRecoverer.REJECTING; RELEASING is also available. You can set a custom recoverer on the factory or container.

  • See Share consumer error handling in the Kafka Queues documentation.

Share Consumer Lifecycle Events

ShareKafkaMessageListenerContainer now publishes stop and failure lifecycle events in addition to ConsumerStartingEvent and ConsumerStartedEvent:

  • ShareConsumerStoppingEvent (new): published before the underlying ShareConsumer is closed. A new event class is introduced because ShareConsumer is a separate client API from Consumer, so the existing ConsumerStoppingEvent is not reusable.

  • ConsumerStoppedEvent: published after the share consumer is closed, with a reason of NORMAL, ABNORMAL, or ERROR.

  • ConsumerFailedToStartEvent: published when a share consumer fails to start. Any already-constructed consumers from the same startup attempt are closed quietly.

See Lifecycle Events for details.

ShareAcknowledgment.renew()

ShareAcknowledgment now supports renew() to extend the acquisition lock when processing exceeds the broker’s lock duration (KIP-1222, Kafka 4.2). See ShareAcknowledgment API in the Kafka Queues documentation for details.

RetryTopicConfigurationBuilder Default Strategy Change

The default value of sameIntervalTopicReuseStrategy in RetryTopicConfigurationBuilder has been changed from MULTIPLE_TOPICS to SINGLE_TOPIC to align with the @RetryableTopic annotation default. See Topic Naming for more information.

Kafka Streams Native DLQ Support

Spring for Apache Kafka now provides exception handlers that support Kafka Streams DLQ (KIP-1034, Kafka 4.2):

The provided exception handlers support multiple Kafka Streams DLQ enabling strategies and dead-letter topic resolution options:

RecoveringDeserializationExceptionHandler.KSTREAM_DESERIALIZATION_RECOVERER has been deprecated in favor of RecoveringDeserializationExceptionHandler.RECOVERER to align with the new handlers properties.

Kafka Streams Group Protocol Configuration

The StreamsBuilderFactoryBean now supports configuring the groupProtocol property. This allows you to explicitly manage whether the underlying Kafka Streams consumers rely on the classic protocol or opt into the newer streams group protocol (KIP-1071: Server-side rebalance for Streams).

See Configuration in the Kafka Streams documentation for more details.