🚨 Kafka Error Guide: 'GroupMaxSizeReachedException: Consumer group has reached maximum size' — Fix Oversized Consumer Groups

Overview

GroupMaxSizeReachedException is returned to a consumer trying to join a group that already has the maximum number of members allowed by the broker’s group.max.size:

org.apache.kafka.common.errors.GroupMaxSizeReachedException: Consumer group orders already has the configured maximum number of members.
[2026-07-09 08:47:19] ERROR [Consumer clientId=orders-27, groupId=orders] Attempt to join group failed: group has reached its maximum size

The rejected consumer cannot join, so it processes nothing. The broker enforces this cap to protect the group coordinator from runaway membership. The real question is why so many members are trying to join.

Symptoms

• New consumer instances fail to join a group and log GroupMaxSizeReachedException, then idle.
• The affected group’s member count sits at exactly group.max.size.
• Some partitions still get consumed while the rejected instances do nothing, causing lag on the unassigned share.
• The error appears after scaling out consumers or after a deploy that leaked old instances.
• Restarting the rejected consumer does not help until existing members leave.

Common Root Causes

• Genuinely more consumers than the cap — the group scaled past group.max.size (default is generous but finite).
• Leaked consumer instances — old pods/processes did not close cleanly and still hold membership until session timeout, so live instances hit the cap.
• Duplicate instances from a bad deploy — a rolling deploy started new members before old ones left, doubling membership briefly.
• Session timeout too high — dead members linger for a long session.timeout.ms, keeping their slots occupied.
• More consumers than partitions plus a low cap — deploying far more instances than partitions (they would idle anyway) can bump into a lowered cap.

Diagnostic Workflow

Count current members of the group and see their assignments:

kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
  --describe --group orders --members --verbose

Check the configured cap on the brokers:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-default --describe | grep -i group.max.size

Compare member count against partition count (extra members idle anyway):

kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders | grep -c Partition

Look for members that are unassigned or duplicated (leaked instances):

kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
  --describe --group orders --members | awk '$4 == 0 {print}'

Example Root Cause Analysis

After a routine deployment, on-call saw new orders consumer pods failing to start with GroupMaxSizeReachedException, while lag on a subset of partitions grew.

kafka-consumer-groups.sh --describe --group orders --members showed the group at its group.max.size cap, but many members had zero partitions assigned and client-ids matching the previous deployment. The old pods had been terminated with SIGKILL by an aggressive shutdown, so they never sent a LeaveGroup; their membership persisted until the 45-second session.timeout.ms expired. Because the deploy rolled fast, new pods tried to join while the dead ones still occupied slots, hitting the cap.

Two fixes applied. Short term: the leaked members aged out after session.timeout.ms and the new pods joined on retry — the error was transient. Long term: the shutdown hook was fixed to call consumer.close() (sending an explicit LeaveGroup) so members release their slots immediately, and the deploy was set to drain old pods before starting new ones. The group.max.size was left as a safety cap, correctly doing its job of catching runaway membership.

Prevention Best Practices

• Ensure consumers call close() on shutdown so they send LeaveGroup and free their slot immediately instead of lingering.
• Use graceful termination (honor SIGTERM, avoid SIGKILL) and drain old instances before starting new ones during deploys.
• Do not run more consumer instances than partitions — extra members idle and only consume group slots.
• Tune session.timeout.ms so dead members are detected reasonably fast without causing false evictions.
• Keep group.max.size as a deliberate guardrail; if you legitimately need more members, raise it consciously rather than by reflex.
• Alert on consumer members with zero partition assignments — a sign of leaked or excess instances.

Quick Command Reference

# Members and their assignments
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group orders --members --verbose

# The configured cap
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --describe | grep group.max.size

# Partition count (members beyond this idle)
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders | grep -c Partition

# Raise the cap deliberately if truly needed
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --alter --add-config group.max.size=500

Conclusion

GroupMaxSizeReachedException means a consumer group hit the group.max.size cap, and the broker refused a new member to protect the coordinator. Occasionally the cap is genuinely too low, but far more often the group is bloated with leaked or duplicated members from unclean shutdowns and fast deploys. Fix the consumer lifecycle so instances call close() and leave cleanly, drain before scaling, keep instance count within partition count, and treat the cap as the guardrail it is meant to be.