Exactly-Once Semantics

A stream processor handles an order, writes its result, and crashes. After restarting, it handles the order again. Its logs show two attempts, yet a downstream reader sees only one committed result.

That can be correct exactly-once behavior. The guarantee concerns the effects that survive recovery, even when the application executes the work more than once.

In this chapter, we’ll define that guarantee, follow a Kafka processing attempt through failure, and examine the roles of transactions, state recovery, and consumer isolation. We’ll also identify where the guarantee ends: duplicate source events, deliberate replay, and external systems need their own treatment.

The examples use Apache Kafka 4.3.1, its Java clients, and ordinary consumer groups in a KRaft-based cluster. Unless stated otherwise, processing stays within one Kafka cluster, required records and recovery state remain available, and applications resume from valid committed positions.