apache/dolphinscheduler · critical · RegistryException

zookeeper connect failed to: in : ms

Error message

zookeeper connect failed to:  in : ms

What it means

Thrown by ZookeeperRegistry.start() when the Curator client cannot establish a connection to the ZooKeeper ensemble within the configured blockUntilConnected duration. The connect string and timeout are included in the message. Start fails and the client is closed, so the registry is unusable.

Source

Thrown at dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-zookeeper/src/main/java/org/apache/dolphinscheduler/plugin/registry/zookeeper/ZookeeperRegistry.java:108

                        @Override
                        public List<ACL> getAclForPath(final String path) {
                            return ZooDefs.Ids.CREATOR_ALL_ACL;
                        }
                    });
        }
        client = builder.build();
    }

    @Override
    public void start() {
        final StopWatch stopWatch = StopWatch.createStarted();
        client.start();
        try {
            if (!client.blockUntilConnected(DurationUtils.toMillisInt(properties.getBlockUntilConnected()),
                    MILLISECONDS)) {
                client.close();
                throw new RegistryException(
                        "zookeeper connect failed to: " + properties.getConnectString() + " in : "
                                + properties.getBlockUntilConnected().toMillis() + "ms");
            }
            stopWatch.stop();
            log.info("ZookeeperRegistry started at: {}/ms", stopWatch.getTime());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RegistryException("Zookeeper registry start failed", e);
        }
    }

    @Override
    public void addConnectionStateListener(ConnectionListener listener) {
        client.getConnectionStateListenable().addListener(new ZookeeperConnectionStateListener(listener));
    }

    @Override
    public void connectUntilTimeout(@NonNull Duration timeout) throws RegistryException {

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify the connect string (host:port list) in the registry configuration and test reachability with nc/telnet
  2. Increase blockUntilConnected (and session timeout) in the registry properties
  3. Check ZooKeeper server health and logs on the ensemble
  4. Check network/firewall/DNS between the client and the ensemble
  5. Retry start() after fixing connectivity; consider a connection-state retry loop

Example fix

// before
zookeeper.connect.string=localhost:2181
zookeeper.block.until.connected=1s
// after
zookeeper.connect.string=zk1:2181,zk2:2181,zk3:2181
zookeeper.block.until.connected=30s
Defensive patterns

Strategy: validation

Validate before calling

for (String hostPort : connectString.split(",")) {
    String[] hp = hostPort.split(":");
    try (Socket s = new Socket()) {
        s.connect(new InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 3000);
    } catch (IOException e) {
        throw new IllegalStateException("ZooKeeper unreachable: " + hostPort, e);
    }
}

Type guard

boolean zookeeperReachable(String connectString) {
    return Arrays.stream(connectString.split(","))
        .allMatch(hp -> {
            String[] p = hp.trim().split(":");
            try (Socket s = new Socket()) {
                s.connect(new InetSocketAddress(p[0], Integer.parseInt(p[1])), 3000);
                return true;
            } catch (IOException e) { return false; }
        });
}

Try / catch

try {
    registry.start();
} catch (RegistryException e) {
    log.error("Cannot connect to ZooKeeper at {}: {}", connectString, e.getMessage());
    throw new IllegalStateException("Registry unavailable, check zookeeper.quorum", e);
}

Prevention

When it happens

Trigger: Calling start() (directly or via connectUntilTimeout on a fresh instance) when the ZooKeeper servers at properties.getConnectString() are unreachable or do not accept the session within properties.getBlockUntilConnected().

Common situations: Wrong zookeeper.quorum host/port in configuration; ZooKeeper ensemble down or unreachable due to firewall/DNS; SASL/quorum auth mismatch; long GC or slow network exceeding the block timeout.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/a2f7404bc193bf3c. Report an issue: GitHub.