apache/pulsar · error · IOException

Interrupted when connecting to zookeeper server

Error message

Interrupted when connecting to zookeeper server

What it means

waitForConnection blocks on a ZooKeeper client connect latch up to zkSessionTimeOut milliseconds. If the awaiting thread is interrupted (Thread.interrupt()), the InterruptedException is converted into this IOException with the original interrupt as the cause. It signals the startup/shutdown path was cancelled while waiting for the ZK session to establish, not that the server refused the connection.

Source

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

    /* 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();
                    outstream.write("stat".getBytes());
                    outstream.flush();

View on GitHub (pinned to 820761864e)

Solutions

1. Investigate who interrupts the thread (enable -Djava.util.concurrent.FastThreadLocal / log at Thread.currentThread().interrupt() sites) and avoid interrupting during ZK bootstrap.
2. Ensure the ZooKeeper server is up and reachable so the latch counts down quickly and the window for interruption is minimal (waitForServerUp before init).
3. Increase zkSessionTimeOut if interruption comes from an external timeout racing the connect.
4. Handle shutdown explicitly: check the interrupt cause and retry initialization on a fresh thread if it was spurious.

Example fix

// before
ensemble.start();
// after
Thread t = new Thread(() -> {
    try { ensemble.start(); } catch (IOException e) {
        if (e.getCause() instanceof InterruptedException) {
            Thread.currentThread().interrupt(); // preserve status, retry or abort cleanly
        }
    }
});
t.start();

// before init
if (!LocalBookkeeperEnsemble.waitForServerUp(zkHost, zkPort, 30000)) {
    throw new IllegalStateException("ZK not up; fix environment before initializing");
}

try {
    ensemble.start();
} catch (IOException e) {
    if (e.getCause() instanceof InterruptedException) {
        Thread.currentThread().interrupt();
        // abort startup cleanly or retry once on a non-interrupted thread
    }
    throw e;
}

When it happens

Trigger: LocalBookkeeperEnsemble.initializeZookeper() -> waitForConnection() while zkClient.connect() has not yet completed and another thread interrupts the calling thread (e.g. shutdown hook, future cancellation, service stop).

Common situations: Broker/standalone startup aborted during graceful shutdown; a watchdog or test framework timing out and interrupting the bootstrap thread; calling initializeZookeper on a thread pool whose task was cancelled.

Related errors

• Could not open configuration file
• Failed to refresh self owner info.
• Cannot create temp directory
• Failed to create base storage directory at ${storagePath}
• Failed to start zookeeper :${e.getMessage()}

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