What an offset tells the consumer
An offset identifies progress through a Kafka partition. Committing it communicates where a consumer group should resume, but that progress marker is not automatically proof that an external database update or remote business action completed correctly. The listener's acknowledgment policy must match the operation's durability and replay design.
Spring Kafka supports several acknowledgment modes, and their behavior depends on container configuration and transaction use. This guide examines the business boundary around that configuration. It does not claim that enabling one option creates exactly-once effects across every external system.
Setup: write the processing sequence
Document the topic, consumer group, partition key, listener mode and commit policy. Draw the sequence from record receipt to database commit, remote side effect and acknowledgment. Identify where a process can fail between steps and what the next attempt will observe.
The Spring Kafka reference explains record and batch commit modes and notes configuration differences across releases. Inspect the effective settings of the deployed listener rather than relying on a remembered framework default. Establish a durable event or business-operation identity that survives retries and can support reconciliation.
Illustrative incident: the offset advanced, the effect did not
An illustrative inventory listener acknowledges progress before a downstream write is durable. The process stops, restarts beyond that record and leaves a missing business update. A different failure after a durable write but before acknowledgment causes replay instead. These are constructed examples of different failure windows, not client case studies.
Use synthetic records and controlled stop points. Correlate topic, partition, offset, operation identity and committed outcome. Keep message payloads and personal fields out of broad incident logs when identifiers are sufficient to explain progress.
Troubleshooting: locate the failure window
| Observation | Evidence | Question |
|---|---|---|
| Missing effect after restart | Commit timing and durable result | Was progress recorded before the effect? |
| Duplicate effect after replay | Operation identity and result lookup | Can the consumer recognize completed work? |
| Consumer repeatedly processes one failure | Error handler and retry classification | Is an unrecoverable record blocking progress? |
| Rebalances occur during slow processing | Poll timing and processing duration | Does workload fit the consumer configuration? |
Do not reset offsets broadly as an exploratory repair. A reset can replay substantial business history or skip required records. First establish the affected range and whether repeated effects are safe.
Corrective action and retry ownership
Align acknowledgment with the intended durability boundary and the supported Spring Kafka transaction model. Where the database or remote service is outside that atomic boundary, use idempotency and reconciliation. Preserve record ordering requirements for the business key; higher concurrency is not always compatible with them.
Separate transient failures from records that require correction or review. Define terminal failure handling and retain enough protected evidence for a controlled replay. A dead-letter destination is useful only when someone owns its age, investigation and recovery. Avoid retrying an external charge or notification solely because the listener did not see a successful acknowledgment.
Verification, freshness SLO and SOP
Test failure before the business write, after the write and before offset commit, during acknowledgment and during consumer rebalance. Verify final business state as well as consumer lag. Replayed records should converge on the intended outcome without inventing a guarantee beyond the actual system boundary.
An internal SLO can measure eligible event processing and business freshness, while lag and commit rate serve as supporting signals. A customer SLA needs explicit dependency and replay assumptions. The SOP should name offset-reset authority, replay range selection, deduplication evidence, failure-queue ownership and escalation criteria.
Explore software development and observability and monitoring.
Technical reference
Spring Kafka listener containers and offset commits, reviewed 19 October 2026. Follow documentation matching the installed product version.