Kafka Error `GROUP_MAX_SIZE_REACHED`

Error code 81 · Non-retriable Consumer

The group has reached its maximum size.

Common Causes

Consumer group has more active members than the configured limit for that protocol (`group.max.size` for classic groups, or `group.consumer.max.size` for consumer-protocol groups)
Rolling restart or deployment added new consumer instances before old ones left, temporarily exceeding the limit
Multiple consumer group instances sharing the same group.id across different services or environments

Solutions

Increase the applicable broker limit for the protocol in use (`group.max.size` for classic groups or `group.consumer.max.size` for consumer-protocol groups), or reduce the number of consumer instances to stay within the current limit
Ensure old consumer instances are fully shut down before deploying new ones; use graceful shutdown with consumer.close() to trigger a leave-group before adding replacements
Audit group membership with kafka-consumer-groups.sh --describe and kill stale/orphaned members that are not processing

Diagnostic Commands

# Describe consumer group offsets and lag
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group <group-id>

# Check consumer group max size settings
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --describe | grep -E 'group.max.size|group.consumer.max.size'

Related APIs

This error can be returned by: JoinGroup

Related KIPs

KIP-389

Debugging Kafka errors? Conduktor Console gives you real-time visibility into your cluster. Explore all errors in the Error Decoder.