Kafka Error STREAMS_TOPOLOGY_FENCED
Error code 132 · Non-retriable Streams
The supplied topology epoch is outdated.
Common Causes
- The Kafka Streams application's topology epoch is outdated — another instance or a newer deployment has updated the topology and advanced the epoch, fencing this instance's epoch as stale.
- Rolling deployment of a Streams application with topology changes: old instances still running with the previous topology epoch get fenced when the new deployment pushes a topology update with a higher epoch.
- Network partition caused the Streams instance to miss topology epoch updates from the broker; when it reconnected, its epoch was several versions behind the current epoch.
Solutions
- The fenced Streams instance must stop processing, fetch the current topology from the broker, and reinitialize with the new topology and epoch. This typically means restarting the Streams application.
- During rolling deployments with topology changes, ensure old instances are fully drained and stopped before new instances push topology updates. Use blue/green deployment patterns for topology-changing upgrades.
- Monitor for this error in production as it indicates topology version skew across your Streams fleet. Set up alerts and automated restarts for fenced instances to minimize processing gaps.
Diagnostic Commands
# Look for epoch fencing events in logs
grep 'STREAMS_TOPOLOGY_FENCED\|topology fenced\|topology epoch' /var/log/kafka/server.log | tail -50
# Check finalized feature versions in cluster
kafka-features.sh --bootstrap-server localhost:9092 describeRelated 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.