Kafka "Broker may not be available" / NoBrokersAvailable in CI

The client reached (or tried to reach) the bootstrap server but could not get broker metadata before the timeout, so it reports "Broker may not be available" or raises NoBrokersAvailable. The usual cause is connecting before the broker is ready or pointing at the wrong bootstrap address.

What this error means

A producer or consumer fails with "kafka.errors.NoBrokersAvailable: NoBrokersAvailable" or repeated "Broker may not be available" warnings, then a metadata timeout.

Terminal

kafka.errors.NoBrokersAvailable: NoBrokersAvailable

Common causes

The client connects before the broker is ready

Metadata fetch fails while the broker is still starting or forming its KRaft quorum, so the client sees no available brokers.

The bootstrap server address is wrong

A bootstrap.servers that does not match the mapped port (or the advertised listener) leaves the client with no reachable broker.

How to fix it

Wait for broker readiness before connecting

Loop on an admin call until the broker answers, then run the client.

Terminal

until kafka-broker-api-versions.sh --bootstrap-server localhost:9092 >/dev/null 2>&1; do
  echo "waiting for kafka broker"; sleep 3
done

Point bootstrap.servers at the mapped address

Use the published host:port that matches the broker advertised listener.

.github/workflows/ci.yml

env:
  KAFKA_BOOTSTRAP_SERVERS: localhost:9092

How to prevent it

Wait for the broker to answer an admin call before producing or consuming.
Keep bootstrap.servers aligned with the advertised listener.
Allow enough metadata timeout for a slow first broker start.