Kafka Error STREAMS_INVALID_TOPOLOGY_EPOCH
Error code 131 · Non-retriable Streams
The supplied topology epoch is invalid.
Common Causes
- The Kafka Streams application sent a topology update with an epoch that doesn't match the broker's current epoch for that topology — the client's epoch tracking is out of sync with the broker.
- Concurrent topology updates from multiple Streams application instances attempted to update the same topology simultaneously, causing one update's epoch to be invalidated by the other.
- Client reconnected and is using a cached topology epoch from before the reconnection, while the broker advanced the epoch during the disconnection period.
Solutions
- Refresh the topology epoch by re-fetching the current topology state from the broker before retrying the update. The Kafka Streams client should handle this automatically on error.
- Ensure only one application instance manages topology updates at a time. Use distributed coordination (e.g., application-level locking) if multiple instances may attempt topology updates concurrently.
- Restart the Streams application to force a fresh epoch negotiation if the epoch tracking becomes permanently desynchronized.
Diagnostic Commands
# Check finalized feature versions in cluster
kafka-features.sh --bootstrap-server localhost:9092 describe
# Look for topology events in logs
grep 'STREAMS_INVALID_TOPOLOGY_EPOCH\|topology epoch\|StreamsTopology' /var/log/kafka/server.log | tail -30Related APIs
This error can be returned by: StreamsGroupHeartbeat
Debugging Kafka errors? Conduktor Console gives you real-time visibility into your cluster. Explore all errors in the Error Decoder.