Kafka Error FENCED_STATE_EPOCH
Error code 124 · Non-retriable Share Groups
The share coordinator rejected the request because the share-group state epoch did not match.
Common Causes
- The share coordinator received a request with a share-group state epoch that is outdated — another coordinator instance (or a coordinator failover) has already advanced the epoch, fencing the request.
- Share coordinator failover occurred mid-operation: the original coordinator advanced the state epoch but the client's subsequent request went to the new coordinator which had a different epoch view.
- Concurrent requests from multiple share group consumers triggered conflicting state updates, causing one request's epoch to be fenced by a concurrent write that succeeded first.
Solutions
- The client must refresh its view of the share-group state epoch by re-fetching coordinator metadata and retrying with the correct epoch. Do not cache state epochs across coordinator reconnections.
- Ensure share group coordinator stability: avoid frequent coordinator reassignments by ensuring the `__share_group_state` internal topic has adequate replication and its partitions have stable leaders.
- Reduce concurrent share group state mutations by serializing consumer group membership changes. Avoid simultaneous add/remove of multiple share consumers.
Diagnostic Commands
# Describe share group state and members
kafka-share-groups.sh --bootstrap-server localhost:9092 --describe --group <share-group-id>
# Look for epoch fencing events in logs
grep 'FENCED_STATE_EPOCH\|share.group.state\|share coordinator' /var/log/kafka/server.log | tail -50Related APIs
This error can be returned by: ShareAcknowledge · ShareFetch
Debugging Kafka errors? Conduktor Console gives you real-time visibility into your cluster. Explore all errors in the Error Decoder.