Monedula

Scenario 11.0.3 · Record acquisition locks and lock timeout

Kafka share group acquisition lock timeout and redelivery

Share groups · Intermediate · about 3 min · Apache Kafka 4.3

An acquired record is LOCKED to one member; if it is not acknowledged before the lock times out it is released and becomes re-acquirable (KIP-932).

Run this scenario in the playground

Re-acquired · deliveryCount climbs. t+1.850s

The next poll (1800ms) re-acquires the now-available offset 0 - locked to w1 again with deliveryCount=2. A released record is redelivered; the delivery count tracks how many times.

Open at this step: step 5, Re-acquired · deliveryCount climbs

What you start with

When a share-group member acquires a record it holds an acquisition LOCK: the record is in-flight and invisible to other members until it is acknowledged or the lock expires. With explicit ack mode, the single member here acquires a record but never acks it, so the 900ms lock times out, the record returns to AVAILABLE, and the next poll re-acquires it (deliveryCount climbs) - until a late accept finally ends the loop.

Step by step

  1. Cluster ready · idle t+0.000s One partition, one share group (single member w1) in EXPLICIT ack mode with a 900ms acquisition lock. Press ▶. Open at this step: step 1, Cluster ready · idle
  2. Record acquired · locked to w1 t+0.700s First poll (600ms) acquires offset 0: state 'acquired', locked to w1 until 1500ms, deliveryCount=1. In explicit mode it stays in-flight - no auto-accept - until acked or the lock expires. Open at this step: step 2, Record acquired · locked to w1
  3. Still held · lock not yet expired t+1.300s A later poll (1200ms) finds nothing to do: offset 0 is still locked to w1, so no other delivery can take it. The record is held, un-acked, waiting on the lock. Open at this step: step 3, Still held · lock not yet expired
  4. Lock timed out · record released t+1.550s The 1500ms lock expired with no acknowledgement, so offset 0 is RELEASED back to 'available' (deliveryCount stays 1). An un-acked lock does not hold a record forever - it returns to the queue. Open at this step: step 4, Lock timed out · record released
  5. Re-acquired · deliveryCount climbs t+1.850s The next poll (1800ms) re-acquires the now-available offset 0 - locked to w1 again with deliveryCount=2. A released record is redelivered; the delivery count tracks how many times. Open at this step: step 5, Re-acquired · deliveryCount climbs
  6. Accepted · loop ends t+2.050s This time w1 explicitly accepts offset 0 (→ 'acked') before the lock expires. Accept is terminal: the record will not be redelivered again. Open at this step: step 6, Accepted · loop ends

The takeaway

The acquisition lock is the safety net behind at-least-once delivery: an un-acked record is automatically released and redelivered, so a stalled or crashed consumer never silently drops work.

Embed this scenario

Paste this into a blog post, a course page or your team's docs. The scenario plays inside your page, and the link under it points readers to this walkthrough.

<iframe src="https://monedula.dev/kafka-simulator/embed/?scenario=11.0.3" title="Kafka Simulator: Record acquisition locks and lock timeout" width="100%" height="520" style="border:1px solid #d0d0d0;border-radius:8px" loading="lazy"></iframe>
<p><a href="https://monedula.dev/kafka-simulator/scenarios/acquisition-lock-timeout/">Kafka share group acquisition lock timeout and redelivery</a></p>

Further reading

KIP-932 on the Apache Kafka wiki

More in Share groups

All scenarios