Kafka Error INVALID_SHARE_SESSION_EPOCH
Error code 123 · Retriable Share Groups
The share session epoch is invalid.
Common Causes
- The client sent a `ShareFetch` request with an epoch that doesn't match the broker's expected next epoch for the session — typically because the client missed or dropped a response that incremented the epoch on the broker side.
- Network error caused a `ShareFetch` response to be lost; the client retried with the same epoch but the broker had already advanced, causing an epoch mismatch.
- Bug in client epoch tracking: the client failed to increment its local epoch after a successful `ShareFetch` response, causing all subsequent requests to use a stale epoch.
Solutions
- The error is retriable — the client should close the current share session (epoch=-1) and recreate it by sending a new `ShareFetch` with epoch=0. The Kafka client library handles this recovery automatically.
- Ensure reliable network connectivity between consumer and broker to avoid lost responses that cause epoch divergence. Use appropriate `request.timeout.ms` values.
- If implementing a custom share group consumer, strictly follow the epoch increment protocol: increment local epoch by 1 for each successful response received, and use epoch=-1 to signal session close.
Diagnostic Commands
# Describe share group state and members
kafka-share-groups.sh --bootstrap-server localhost:9092 --describe --group <share-group-id>
# Look for share session events in logs
grep 'INVALID_SHARE_SESSION_EPOCH\|ShareFetch\|share session epoch' /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.