Introduction

When topic creation fails in a Docker Compose Kafka setup, the problem is usually not Docker Compose itself. It is almost always one of four things: the broker is not ready yet, the listener configuration is wrong, the command is targeting the wrong hostname or port, or the requested replication settings do not match the number of brokers you actually started.

Start With a Minimal Working Setup

A single-broker local setup should use a single replication factor. If you ask Kafka for a replication factor of 3 while running one broker, topic creation will fail.

A simple Compose example for local development looks like this:

1services:
2  kafka:
3    image: confluentinc/cp-kafka:7.6.0
4    ports:
5      - "9092:9092"
6    environment:
7      KAFKA_NODE_ID: 1
8      KAFKA_PROCESS_ROLES: broker,controller
9      KAFKA_LISTENERS: PLAINTEXT://kafka:9092,CONTROLLER://kafka:9093
10      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
11      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
12      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
13      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
14      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
15      CLUSTER_ID: MkU3OEVBNTcwNTJENDM2Qk

The important part is consistency between listeners, advertised listeners, and the client command you use.

Create the Topic After the Broker Is Ready

Even if the container is running, Kafka may not be ready to accept admin commands yet. That is why commands executed immediately after docker compose up often fail.

Create the topic from inside the container using the broker's internal address.

docker compose exec kafka kafka-topics   --create   --topic orders   --partitions 1   --replication-factor 1   --bootstrap-server kafka:9092

For a single container, kafka:9092 is usually the correct internal bootstrap address. From your host machine, the advertised external address is often localhost:9092.

Common Failure Modes

Wrong Bootstrap Server

If you run the command inside the container, do not use localhost:9092 unless the broker is באמת listening there in that container context. Inside Docker networking, the service name is often the right host.

Wrong Replication Factor

One broker supports replication factor 1. Asking for 2 or 3 on a one-broker stack produces an error.

Bad advertised.listeners

Kafka returns broker addresses to clients. If those addresses are wrong for the environment where the client is running, admin operations fail even though the port looks open.

Running Too Early

The broker process may still be formatting storage, electing a controller, or starting listeners. depends_on starts containers in order, but it does not guarantee Kafka is ready for commands.

A Reliable Readiness Pattern

The safest approach is to wait for the broker to respond before creating the topic.

1until docker compose exec kafka kafka-topics --bootstrap-server kafka:9092 --list >/dev/null 2>&1; do
2  sleep 2
3done
4
5docker compose exec kafka kafka-topics   --create   --topic orders   --partitions 1   --replication-factor 1   --if-not-exists   --bootstrap-server kafka:9092

This is more reliable than firing the create command immediately after container startup.

Auto-Creation Versus Explicit Creation

Some images and broker settings allow automatic topic creation, but relying on it is often confusing in development because it hides errors in naming and configuration. Explicit admin commands are clearer.

If you use an image-specific environment variable such as KAFKA_CREATE_TOPICS, verify that the image actually supports it. Different Kafka images expose different helper behaviors.

Check the Broker Logs

If topic creation still fails, inspect logs first.

docker compose logs kafka

Look for listener binding errors, advertised listener mismatches, controller startup issues, or storage formatting problems.

Common Pitfalls

A common mistake is creating a topic with replication factor 3 on a one-broker local setup.

Another mistake is using localhost:9092 from inside the Kafka container. Inside Docker networking, the broker is often reachable as kafka:9092 instead.

Developers also assume depends_on means Kafka is ready for admin commands. It only means the container was started, not that the broker finished booting.

Summary

• Topic creation failures in Compose are usually listener, readiness, or replication-factor problems.
• Use replication factor 1 for a single local broker.
• Run admin commands against the correct bootstrap address for the environment.
• Wait until the broker is actually ready before creating topics.
• Check image-specific behavior and broker logs when auto-creation does not work.