Async @KafkaListener ack mode. Should it be MANUAL? What's its best use?

[alexbujenita]

Hi Spring Team,

I wanted to ask you if I'm getting this page correctly.

It says

The AckMode will be automatically set the MANUAL and enable out-of-order commits when async return types are detected; instead, the asynchronous completion will ack when the async operation completes... etc...

Trying this small setup locally (4.0.6) it shows as BATCH

@Component
public class AsyncListener {

    @KafkaListener(topics = "my-topic", groupId = "test-g", id = "test")
    public CompletableFuture<String> listen(String message) {
        return CompletableFuture.completedFuture(message);
    }
}

and logging the props

@Component
public class KafkaConfig {
    private static final Logger log = LoggerFactory.getLogger(KafkaConfig.class);
    private final KafkaListenerEndpointRegistry registry;

    public KafkaConfig(KafkaListenerEndpointRegistry registry) {
        this.registry = registry;
    }

    @EventListener(ApplicationReadyEvent.class)
    public void logContainerProps() {
        MessageListenerContainer container = registry.getListenerContainer("test");

        var containerProperties = container.getContainerProperties();

        log.info("Kafka listener runtime check: containerClass={}", container.getClass().getName());
        log.info("Kafka listener runtime check: asyncAcks={}", containerProperties.isAsyncAcks());
        log.info("Kafka listener runtime check: ackMode={}", containerProperties.getAckMode());
        log.info("Kafka listener runtime check: running={}", container.isRunning());

    }
}

LOGS

Kafka listener runtime check: containerClass=org.springframework.kafka.listener.ConcurrentMessageListenerContainer
Kafka listener runtime check: asyncAcks=false
Kafka listener runtime check: ackMode=BATCH
Kafka listener runtime check: running=true

I was expecting to see MANUAL and not BATCH , or am I checking the wrong thing?

Also in the documentation there not really much describing this behaviour, I can't find a why to this approach, pros vs cons, do non-blocking retries work the same... etc...
For now I'm using it to get many messages and process them concurrently to not create too many partitions for a topic.

Thank you,

Alex.

[lMysticl]

You are checking the configured properties, not the effective acknowledgment mode used by the running ListenerConsumer.

In 4.0.6, the listener adapter detects CompletableFuture from the declared method return type and marks the listener as async: HandlerAdapter. The container then derives a private effective mode:

1. asyncReplies becomes true for that adapter.
2. determineAckMode() reads the configured mode and locally changes it to MANUAL when the listener is async.

That happens inside ListenerConsumer and inside determineAckMode(). It does not mutate the public ContainerProperties object. Therefore these values are expected:

containerProperties.getAckMode() == BATCH
containerProperties.isAsyncAcks() == false

while the running consumer still uses the equivalent of MANUAL plus out-of-order acknowledgments. The documentation's “automatically set” wording describes the effective runtime behavior; it does not mean the original configuration bean is rewritten.

A behavioral test is a better way to verify it: return an incomplete future and check that the offset is not committed until that future completes. If a later record completes first, its commit is deferred until the missing earlier acknowledgment arrives.

One important detail in the sample is that CompletableFuture.completedFuture(...) does not create any concurrency; the work has already finished before the listener returns. For actual asynchronous processing, return the future that represents the whole operation, preferably from a bounded executor:

public CompletableFuture<Void> listen(String message) {
    return CompletableFuture.runAsync(() -> process(message), kafkaWorkerExecutor);
}

This model is useful for I/O-bound work when blocking the consumer thread is undesirable, but it has trade-offs:

• records from the same partition can be processed concurrently and complete out of order;
• commits wait for gaps, and the consumer is paused until all acknowledgments from the previous poll are present;
• a failure can cause duplicate delivery;
• nack() is not supported with out-of-order acknowledgments.

Those last three points are the documented asyncAcks semantics. If per-key/partition completion order is part of the business contract, normal partitioning plus container concurrency is usually the safer scaling mechanism.

Non-blocking retry with @RetryableTopic is supported for async single-record listeners in this line. On exceptional completion, 4.0.6 routes a RuntimeException/ConsumerRecord through the async retry callback: implementation, integration coverage. Make sure failures complete the returned future exceptionally. If the method throws before producing a future, follow the documentation and convert that path to a failed future so it enters the same async handling flow.