Kafka "GroupCoordinator is not available" / CoordinatorNotAvailable in CI

By Kaveh Alemi·Latchkey

A consumer tried to find its group coordinator before the internal __consumer_offsets topic was created and elected. On a single-broker CI container this topic is provisioned a moment after startup, so the first join can race it.

What this error means

A consumer logs "org.apache.kafka.common.errors.CoordinatorNotAvailableException" or "The group coordinator is not available." and retries before joining the group.

Terminal

org.apache.kafka.common.errors.CoordinatorNotAvailableException:
The coordinator is not available.

Common causes

The __consumer_offsets topic is not ready

Consumer groups store offsets in an internal topic that the broker creates and elects leaders for shortly after start. Joining before that fails to find a coordinator.

The offsets topic replication factor is misconfigured

A replication factor higher than the broker count (for example 3 on a single broker) leaves the offsets topic without a valid leader, so no coordinator is available.

How to fix it

Set the offsets replication factor to 1

On a single-broker test container, the internal topics must use replication factor 1.

.github/workflows/ci.yml

services:
  kafka:
    image: bitnami/kafka:3.7
    env:
      KAFKA_CFG_OFFSETS_TOPIC_REPLICATION_FACTOR: '1'
      KAFKA_CFG_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: '1'

Retry the consumer join briefly

Allow the consumer to retry while the coordinator topic finishes electing a leader.

Wait for the broker to answer an admin call before starting the consumer.
Let the client retry CoordinatorNotAvailable for a few seconds.
Confirm the offsets topic exists with kafka-topics.sh --list.

How to prevent it

Set internal-topic replication factors to 1 on single-broker test brokers.
Wait for broker readiness before the first consumer join.
Allow short retries for coordinator discovery.

Frequently asked questions

What causes "Kafka "GroupCoordinator is not available""?