kafka-topics.sh --describe and --list
kafka-topics.sh --describe --topic <name> prints the partition, leader, replica, and ISR layout of a topic, while --list prints every topic name.
When a producer or consumer test fails, the first check is whether the topic exists and has a leader. --describe answers both in one call.
What it does
kafka-topics.sh --list returns the names of all topics. --describe prints per-partition detail: partition id, leader broker, replica set, and the in-sync replica (ISR) set. A partition with leader -1 or "none" has no leader and cannot accept reads or writes.
Common usage
kafka-topics.sh --list --bootstrap-server localhost:9092
kafka-topics.sh --describe --topic orders \
--bootstrap-server localhost:9092
# check only under-replicated partitions
kafka-topics.sh --describe --bootstrap-server localhost:9092 \
--under-replicated-partitionsOptions
| Flag | What it does |
|---|---|
| --list | List all topic names |
| --describe | Print partition/leader/replica/ISR detail |
| --topic <name> | Restrict to one topic |
| --bootstrap-server <host:port> | Broker to query |
| --under-replicated-partitions | Show only partitions missing replicas |
| --unavailable-partitions | Show only partitions with no leader |
In CI
Use --describe as a readiness probe: a topic whose partition shows a valid Leader is safe to produce to. Poll it in a loop until the leader is a real broker id rather than none, then start the test.
Common errors in CI
"LEADER_NOT_AVAILABLE" appears when a topic was just created and leader election has not finished, or when the topic does not exist and auto-create is racing; retry after a short wait. If --describe returns nothing for a topic you expect, it does not exist, so create it first. "Connection to node -1 ... could not be established" means the broker itself is down.