{"record":{"id":"3caccd0b506b9db0","repo":"MyCATApache/Mycat-Server","slug":"failed-to-connect-to-zookeeper-service-url","errorCode":null,"errorMessage":"failed to connect to zookeeper service : {url}","messagePattern":"failed to connect to zookeeper service : (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/main/java/io/mycat/util/ZKUtils.java","lineNumber":75,"sourceCode":"        String url = ZkConfig.getInstance().getZkURL();\n\n        CuratorFramework curatorFramework = CuratorFrameworkFactory.newClient(url, new ExponentialBackoffRetry(100, 6));\n\n        // start connection\n        curatorFramework.start();\n        // wait 3 second to establish connect\n        try {\n            curatorFramework.blockUntilConnected(3, TimeUnit.SECONDS);\n            if (curatorFramework.getZookeeperClient().isConnected()) {\n                return curatorFramework;\n            }\n        } catch (InterruptedException ignored) {\n            Thread.currentThread().interrupt();\n        }\n\n        // fail situation\n        curatorFramework.close();\n        throw new RuntimeException(\"failed to connect to zookeeper service : \" + url);\n    }\n\n    public static void closeWatch(List<String> watchs) {\n        for (String watch : watchs) {\n            closeWatch(watch);\n        }\n    }\n\n    public static void closeWatch(String path) {\n        PathChildrenCache childrenCache = watchMap.get(path);\n        if (childrenCache != null) {\n            try {\n                childrenCache.close();\n            } catch (IOException e) {\n                throw new RuntimeException(e);\n            }\n        }\n    }","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/MyCATApache/Mycat-Server/blob/65f8d8beb752f935752f2a0eec0ab017facab9ef/src/main/java/io/mycat/util/ZKUtils.java#L57-L93","documentation":"ZKUtils.createConnection builds a CuratorFramework client for the given zookeeper URL and blocks retrying until connected; on interrupt/timeout it closes the client and throws RuntimeException('failed to connect to zookeeper service : <url>'). This means Mycat could not establish a session with the ZooKeeper ensemble at startup.","triggerScenarios":"Mycat launched with zk configuration pointing at an unreachable cluster: wrong URL, ZooKeeper down, firewall blocking 2181, or connection never reaching SyncConnected state within the retry policy.","commonSituations":"ZooKeeper not yet started when Mycat boots; cluster address in myid/zk.conf wrong; network/security-group rules; ZooKeeper ensemble quorum lost; session timeout too short for a slow network.","solutions":["Verify ZooKeeper is reachable: run 'echo ruok | nc <host> 2181' (expect 'imok') from the Mycat host","Check the zk URL in the Mycat config matches the actual ensemble addresses and port","Start/repair the ZooKeeper ensemble and ensure quorum is healthy before launching Mycat","Open firewall/security-group access on the client port (2181) and review the retry policy/timeouts if the network is slow"],"exampleFix":"// before\nzkURL=10.0.0.99:2181 // host down\n// after\nzkURL=10.0.0.1:2181,10.0.0.2:2181,10.0.0.3:2181 // reachable ensemble","handlingStrategy":"retry","validationCode":"static boolean zkReachable(String url) {\n    try (java.net.Socket s = new java.net.Socket()) {\n        String[] hp = url.replaceAll(\"^.*?//\",\"\").split(\":\");\n        s.connect(new java.net.InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 3000);\n        return true;\n    } catch (Exception e) { return false; }\n}","typeGuard":null,"tryCatchPattern":"try { ZKUtils.getConnection(); }\ncatch (RuntimeException e) { LOG.error(\"ZK unreachable at \" + url + \", check ensemble/quorum/firewall\", e); throw e; }","preventionTips":["Health-check ZooKeeper ('ruok' four-letter word) before starting Mycat","Use the full ensemble address list, not a single host, in the URL","Ensure firewall/security groups allow the client port from Mycat hosts","Align Curator retry policy/session timeout with your network latency"],"tags":["zookeeper","network","connection","curator"],"backgroundTag":"connection-refused","analyzedSha":"65f8d8beb752f935752f2a0eec0ab017facab9ef","analyzedAt":"2026-09-11T00:12:21.696Z","contentChangedAt":"2026-09-11T00:12:21.696Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}