r/apachekafka • u/Max08081992 • 21h ago
Tool (AI) A consumer group stopped and lag keeps growing: how I debug it, and the CLI I built for it
When a consumer group misbehaves I usually end up piecing it together from
kafka-consumer-groups.sh --describe, lag numbers and broker logs. Most of the
time the cause is one of a handful of things, so I wrote a small open-source CLI
(Go, MIT) that checks for them.
Example: a group that stopped, with messages piling up:
$ mqx group diagnose billing
[warning] empty-with-lag: no members, 25 messages waiting
The group has committed offsets and unconsumed messages but no consumer is running.
Fix: Start the consumers, or if the group is retired delete it with `mqx group delete billing`
It samples the group a couple of times and reports findings with a suggested fix. The rules today:
- stale members left behind by an unclean shutdown
- more members than partitions
- one group id shared by apps subscribed to different topics
- group stuck rebalancing
- empty group that still has lag
- partitions with no committed offset
- uneven assignments
mqx group watch <group> prints a timeline of state changes with rebalance
durations. It handles the classic protocol and KIP-848.
What it is not: a replacement for Kafka UI or AKHQ. It is a terminal tool with no server. It also does peek, publish, offset resets and topic admin, and it speaks RabbitMQ too.
Disclosure: I built most of it with Claude Code, and the repo has integration tests against real brokers (testcontainers).
Repo: https://github.com/Max2535/mqx
Which causes of rebalances or stuck groups have you hit that this list misses? That is what I will add next.