Kafka broker exits because ZooKeeper is not ready in CI

By Kaveh Alemi·Latchkey

In a ZooKeeper-based Kafka setup, the broker must reach ZooKeeper on 2181 to register. If the broker container starts before ZooKeeper is listening, it times out connecting and exits, so the client later sees no broker at all.

What this error means

The Kafka container logs "Timed out waiting for connection while in state: CONNECTING" against ZooKeeper and then shuts down; clients then fail to find any broker.

[ZooKeeperClient Kafka server] Timed out waiting for connection while in state: CONNECTING
kafka.zookeeper.ZooKeeperClientTimeoutException: Timed out waiting for connection

Common causes

The broker started before ZooKeeper was ready

Container start order does not wait for readiness, so the broker tries to connect to a ZooKeeper that is not yet listening on 2181.

Wrong ZooKeeper connect address

The broker zookeeper.connect points at a host or port that does not match the ZooKeeper service.

How to fix it

Wait for ZooKeeper before the broker connects

Poll the ZooKeeper four-letter command until it answers, then start the broker workload.

until echo ruok | nc -w 2 localhost 2181 | grep -q imok; do
  echo "waiting for zookeeper"; sleep 2
done

Point the broker at the correct ZooKeeper

Set zookeeper.connect to the ZooKeeper service host and 2181.

env:
  KAFKA_CFG_ZOOKEEPER_CONNECT: zookeeper:2181

How to prevent it

• Gate the broker on a ZooKeeper readiness check, not just container start.
• Keep zookeeper.connect aligned with the ZooKeeper service address.
• Consider KRaft mode to remove the ZooKeeper dependency entirely.

Frequently asked questions

Related guides

References

• GitHub Actions documentation