apache/pulsar · error · IOException

Couldn't connect to zookeeper server

Error message

Couldn't connect to zookeeper server

What it means

Test/utility harness failure in LocalBookkeeperEnsemble: ZKConnectionWatcher.waitForConnection timed out (or interrupted) waiting on the connect latch for the SyncConnected event, meaning the embedded ZooKeeper server did not accept the client connection within the allotted window; commonly a dead or misconfigured local ZK during test startup.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/zookeeper/LocalBookkeeperEnsemble.java:555

        temporaryDirectories.clear();
    }

    /* Watching SyncConnected event from ZooKeeper */
    public static class ZKConnectionWatcher implements Watcher {
        private final CountDownLatch clientConnectLatch = new CountDownLatch(1);

        @Override
        public void process(WatchedEvent event) {
            if (event.getState() == KeeperState.SyncConnected) {
                clientConnectLatch.countDown();
            }
        }

        // Waiting for the SyncConnected event from the ZooKeeper server
        public void waitForConnection() throws IOException {
            try {
                if (!clientConnectLatch.await(zkSessionTimeOut, TimeUnit.MILLISECONDS)) {
                    throw new IOException("Couldn't connect to zookeeper server");
                }
            } catch (InterruptedException e) {
                throw new IOException("Interrupted when connecting to zookeeper server", e);
            }
        }
    }

    public static boolean waitForServerUp(String hp, long timeout) {
        long start = System.currentTimeMillis();
        String[] split = hp.split(":");
        String host = split[0];
        int port = Integer.parseInt(split[1]);
        while (true) {
            try {
                Socket sock = new Socket(host, port);
                BufferedReader reader = null;
                try {
                    OutputStream outstream = sock.getOutputStream();

View on GitHub (pinned to 820761864e)

Solutions

1. Check local ZooKeeper logs for startup failure (port conflicts, disk issues)
2. Increase the connection wait time or retry starting the local ensemble

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/zookeeper/LocalBookkeeperEnsemble.java:555 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/2b828d54373ce350. Report an issue: GitHub.