{"record":{"id":"a2f7404bc193bf3c","repo":"apache/dolphinscheduler","slug":"zookeeper-connect-failed-to-in-ms","errorCode":null,"errorMessage":"zookeeper connect failed to:  in : ms","messagePattern":"zookeeper connect failed to:  in : ms","errorType":"exception","errorClass":"RegistryException","httpStatus":null,"severity":"critical","filePath":"dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-zookeeper/src/main/java/org/apache/dolphinscheduler/plugin/registry/zookeeper/ZookeeperRegistry.java","lineNumber":108,"sourceCode":"\n                        @Override\n                        public List<ACL> getAclForPath(final String path) {\n                            return ZooDefs.Ids.CREATOR_ALL_ACL;\n                        }\n                    });\n        }\n        client = builder.build();\n    }\n\n    @Override\n    public void start() {\n        final StopWatch stopWatch = StopWatch.createStarted();\n        client.start();\n        try {\n            if (!client.blockUntilConnected(DurationUtils.toMillisInt(properties.getBlockUntilConnected()),\n                    MILLISECONDS)) {\n                client.close();\n                throw new RegistryException(\n                        \"zookeeper connect failed to: \" + properties.getConnectString() + \" in : \"\n                                + properties.getBlockUntilConnected().toMillis() + \"ms\");\n            }\n            stopWatch.stop();\n            log.info(\"ZookeeperRegistry started at: {}/ms\", stopWatch.getTime());\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            throw new RegistryException(\"Zookeeper registry start failed\", e);\n        }\n    }\n\n    @Override\n    public void addConnectionStateListener(ConnectionListener listener) {\n        client.getConnectionStateListenable().addListener(new ZookeeperConnectionStateListener(listener));\n    }\n\n    @Override\n    public void connectUntilTimeout(@NonNull Duration timeout) throws RegistryException {","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-zookeeper/src/main/java/org/apache/dolphinscheduler/plugin/registry/zookeeper/ZookeeperRegistry.java#L90-L126","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Verify the connect string (host:port list) in the registry configuration and test reachability with nc/telnet","Increase blockUntilConnected (and session timeout) in the registry properties","Check ZooKeeper server health and logs on the ensemble","Check network/firewall/DNS between the client and the ensemble","Retry start() after fixing connectivity; consider a connection-state retry loop"],"exampleFix":"// before\nzookeeper.connect.string=localhost:2181\nzookeeper.block.until.connected=1s\n// after\nzookeeper.connect.string=zk1:2181,zk2:2181,zk3:2181\nzookeeper.block.until.connected=30s","handlingStrategy":"validation","validationCode":"for (String hostPort : connectString.split(\",\")) {\n    String[] hp = hostPort.split(\":\");\n    try (Socket s = new Socket()) {\n        s.connect(new InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 3000);\n    } catch (IOException e) {\n        throw new IllegalStateException(\"ZooKeeper unreachable: \" + hostPort, e);\n    }\n}","typeGuard":"boolean zookeeperReachable(String connectString) {\n    return Arrays.stream(connectString.split(\",\"))\n        .allMatch(hp -> {\n            String[] p = hp.trim().split(\":\");\n            try (Socket s = new Socket()) {\n                s.connect(new InetSocketAddress(p[0], Integer.parseInt(p[1])), 3000);\n                return true;\n            } catch (IOException e) { return false; }\n        });\n}","tryCatchPattern":"try {\n    registry.start();\n} catch (RegistryException e) {\n    log.error(\"Cannot connect to ZooKeeper at {}: {}\", connectString, e.getMessage());\n    throw new IllegalStateException(\"Registry unavailable, check zookeeper.quorum\", e);\n}","preventionTips":["Verify the connect string lists reachable host:port nodes before startup","Set a generous blockUntilConnected for slow networks or cold starts","Monitor ZooKeeper ensemble health and quorum status","Check firewall/DNS/SASL settings when migrating environments"],"tags":["zookeeper","network","startup","timeout"],"backgroundTag":"connection-refused","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}