Introduction

A Kafka command that mentions ZooKeeper often fails for one of two reasons: the ZooKeeper address is wrong, or the command itself is from an older Kafka workflow that should now use brokers instead. In modern Kafka, many administrative tasks that once used --zookeeper have moved to --bootstrap-server, and clusters may run in KRaft mode with no ZooKeeper at all.

First Question: Is This Even a ZooKeeper-Based Cluster?

Before debugging the command, confirm whether your Kafka deployment still uses ZooKeeper. Older Kafka clusters used ZooKeeper for metadata coordination. Current Kafka deployments can run in KRaft mode, where broker metadata is managed without ZooKeeper.

If the cluster is KRaft-based, any command that depends on --zookeeper is the wrong command path and will fail no matter how carefully you type the host and port.

That means your first check should be architectural, not syntactic.

Legacy --zookeeper Versus Current --bootstrap-server

Many older examples on the internet look like this:

kafka-topics.sh --zookeeper localhost:2181 --list

For modern broker-based administration, the safer pattern is:

kafka-topics.sh --bootstrap-server localhost:9092 --list

The same shift applies to several other admin tasks. If the goal is topic creation, description, alteration, or consumer-group administration, start by checking whether the command should target brokers rather than ZooKeeper.

What a Real ZooKeeper Connectivity Problem Looks Like

If you really are using a ZooKeeper-based cluster, then the next layer of debugging is straightforward:

• verify the host and port in the connection string
• verify the ZooKeeper process is running
• verify network reachability from the machine running the command
• verify the broker configuration matches the same ensemble

For example, a local check might look like this:

nc -vz localhost 2181

If the port is not reachable, the Kafka command will not be able to reach ZooKeeper either.

You should also check the broker configuration to confirm the expected ZooKeeper endpoints.

zookeeper.connect=zk1:2181,zk2:2181,zk3:2181

If the command points to one address and the brokers use another, you are debugging the wrong target.

Common Command Mismatch Scenarios

A lot of “Kafka to ZooKeeper command produces error” cases are really one of these mismatches:

• using an old command example against a current Kafka release
• using a ZooKeeper command against a KRaft cluster
• pointing to the wrong ZooKeeper port or host
• using a local hostname that does not resolve in the current environment
• expecting the broker port such as 9092 to be usable where a ZooKeeper port such as 2181 is required

The last one is surprisingly common. Kafka broker ports and ZooKeeper ports are not interchangeable.

Replace Old Admin Flows With Broker-Based Commands

If you are maintaining scripts, do not stop at making the old command work once. Update the script to the supported broker-based version.

1kafka-topics.sh \
2  --bootstrap-server broker1:9092 \
3  --create \
4  --topic orders \
5  --partitions 3 \
6  --replication-factor 2

This is more future-proof than continuing to depend on ZooKeeper-facing administration unless you truly need a legacy-only operation.

Read the Error Message Literally

The exact error text matters. “Connection refused” usually means the target port is wrong or the service is down. “Unrecognized option” often means the command syntax changed. “No such znode” or similar coordination errors point more toward a real ZooKeeper issue inside a legacy deployment.

Do not compress all failures into one “Kafka-ZooKeeper problem.” The failure class determines whether you should fix connectivity, command syntax, or architecture assumptions.

Common Pitfalls

A common mistake is copying a --zookeeper example from an old blog post into a modern Kafka installation. Another is forgetting that KRaft clusters do not use ZooKeeper at all.

It is also easy to test connectivity from the wrong host. A command may work on the broker machine but fail from an admin workstation because of firewall rules or hostname resolution.

Finally, do not assume every Kafka script kept the same options across releases. Check the command help for the actual release you are running.

Summary

• First determine whether the cluster still uses ZooKeeper or now runs in KRaft mode.
• For many modern Kafka admin tasks, use --bootstrap-server instead of --zookeeper.
• If the cluster is ZooKeeper-based, verify host, port, reachability, and broker configuration.
• Treat syntax errors, connection errors, and metadata errors as different problems.
• Update legacy scripts to broker-based administration where possible.