kafka-topics.sh --create: Make Topics Before Tests
kafka-topics.sh --create --topic <name> --bootstrap-server <host:port> creates a Kafka topic with the partitions and replication factor you specify.
Integration tests against Kafka usually need their topics to exist first. Creating them explicitly in a setup step is more reliable than depending on auto-create, which is off by default in many images.
What it does
kafka-topics.sh is the admin CLI shipped in the Kafka bin/ directory. With --create it asks the broker to create a topic with a given partition count and replication factor. It talks to the broker over the admin protocol via --bootstrap-server (the older --zookeeper flag was removed in Kafka 3.0).
Common usage
kafka-topics.sh --create \
--topic orders \
--bootstrap-server localhost:9092 \
--partitions 3 \
--replication-factor 1
# idempotent create for CI setup
kafka-topics.sh --create --if-not-exists \
--topic orders --bootstrap-server localhost:9092 \
--partitions 1 --replication-factor 1Options
| Flag | What it does |
|---|---|
| --create | Create a new topic |
| --topic <name> | Topic name to create |
| --bootstrap-server <host:port> | Broker to connect to (replaces --zookeeper) |
| --partitions <n> | Number of partitions |
| --replication-factor <n> | Replicas per partition (max = broker count) |
| --if-not-exists | Do not error if the topic already exists |
| --config <k=v> | Set a topic config, e.g. retention.ms=60000 |
In CI
Create topics in a setup step before the test run, and use --if-not-exists so a retried job does not fail on an existing topic. On a single-broker test cluster, --replication-factor must be 1; higher values fail because there are not enough brokers.
Common errors in CI
"Connection to node -1 (localhost/127.0.0.1:9092) could not be established. Broker may not be available." means the broker is not up yet; wait for it before creating topics. "Replication factor: 3 larger than available brokers: 1" means you asked for more replicas than brokers exist; set --replication-factor 1 on a single-node test cluster. "Topic 'orders' already exists" is fixed by adding --if-not-exists.