kcat -L: List Kafka Brokers and Topics
kcat -L -b <broker> queries the cluster and prints every broker, topic, partition, and partition leader in one shot.
Before producing or consuming, kcat -L confirms the broker is reachable and shows which topics and leaders exist. It is the cheapest Kafka readiness check in a shell.
What it does
kcat -L runs in metadata mode: it connects to the bootstrap broker, fetches cluster metadata, and prints the broker list plus each topic with its partition count and per-partition leader and replica ids. It makes no reads or writes.
Common usage
# full cluster metadata
kcat -L -b localhost:9092
# metadata for a single topic
kcat -L -b localhost:9092 -t orders
# use as a readiness gate in a wait loop
until kcat -L -b localhost:9092 >/dev/null 2>&1; do sleep 1; doneOptions
| Flag | What it does |
|---|---|
| -L | Metadata list mode |
| -b <broker> | Bootstrap broker host:port |
| -t <topic> | Limit metadata to one topic |
| -J | Output metadata as JSON |
| -X <prop=val> | Set a librdkafka config, e.g. security.protocol=SSL |
In CI
Wrap kcat -L in an until loop as a broker readiness probe: it exits non-zero until the broker answers metadata, so the loop naturally blocks until Kafka is ready, then your produce/consume steps run against a live cluster.
Common errors in CI
"% ERROR: Failed to acquire metadata: Local: Broker transport failure" means the broker is not up or the port is wrong; keep polling. If -L lists a broker whose host is an internal container name you cannot resolve, produces will later fail with the same transport error, so fix the advertised listener. "Local: Timed out" points at a firewall or a wrong -b address.