kafka-consumer-groups.sh: Offsets and Lag
kafka-consumer-groups.sh --describe --group <id> shows each partition offset and the lag for a consumer group, and --reset-offsets can rewind it.
Between test runs a consumer group may hold committed offsets that make it skip your fixtures. This tool lets you inspect lag and reset offsets so each run starts clean.
What it does
kafka-consumer-groups.sh manages consumer groups. --list shows group ids, --describe reports current offset, log-end offset, and lag per partition, and --reset-offsets rewrites committed offsets (only when no member of the group is active).
Common usage
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list
kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
--describe --group my-service
# rewind a group to the start before a test (must --execute)
kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
--group my-service --topic orders \
--reset-offsets --to-earliest --executeOptions
| Flag | What it does |
|---|---|
| --list | List all consumer group ids |
| --describe --group <id> | Show offsets and lag for a group |
| --reset-offsets | Change committed offsets (dry-run unless --execute) |
| --to-earliest / --to-latest | Reset target position |
| --to-offset <n> / --shift-by <n> | Reset to an absolute or relative offset |
| --execute | Actually apply the reset (default is a preview) |
In CI
Reset offsets to --to-earliest at the start of a test so the consumer replays your fixtures deterministically. Remember reset only works while the group has no active members; stop your consumer first.
Common errors in CI
"Error: Assignments can only be reset if the group 'my-service' is inactive, but the current state is Stable." means a consumer is still connected; shut it down before resetting. Running --reset-offsets without --execute only prints a preview and changes nothing, which is easy to mistake for a no-op. "Consumer group 'x' does not exist" means nothing has committed under that id yet.