MyCATApache/Mycat-Server · critical · RuntimeException

failed to connect to zookeeper service

Error message

failed to connect to zookeeper service : {url}

What it means

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.

Solutions

1. Verify ZooKeeper is reachable: run 'echo ruok | nc <host> 2181' (expect 'imok') from the Mycat host
2. Check the zk URL in the Mycat config matches the actual ensemble addresses and port
3. Start/repair the ZooKeeper ensemble and ensure quorum is healthy before launching Mycat
4. Open firewall/security-group access on the client port (2181) and review the retry policy/timeouts if the network is slow

Example fix

// before
zkURL=10.0.0.99:2181 // host down
// after
zkURL=10.0.0.1:2181,10.0.0.2:2181,10.0.0.3:2181 // reachable ensemble

static boolean zkReachable(String url) {
    try (java.net.Socket s = new java.net.Socket()) {
        String[] hp = url.replaceAll("^.*?//","").split(":");
        s.connect(new java.net.InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 3000);
        return true;
    } catch (Exception e) { return false; }
}

try { ZKUtils.getConnection(); }
catch (RuntimeException e) { LOG.error("ZK unreachable at " + url + ", check ensemble/quorum/firewall", e); throw e; }

When it happens

Trigger: 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.

Common situations: 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.

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

• ${e}
• ${e}
• errr
• Unexpected exception
• err.errno

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/3caccd0b506b9db0. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/util/ZKUtils.java:75

        String url = ZkConfig.getInstance().getZkURL();

        CuratorFramework curatorFramework = CuratorFrameworkFactory.newClient(url, new ExponentialBackoffRetry(100, 6));

        // start connection
        curatorFramework.start();
        // wait 3 second to establish connect
        try {
            curatorFramework.blockUntilConnected(3, TimeUnit.SECONDS);
            if (curatorFramework.getZookeeperClient().isConnected()) {
                return curatorFramework;
            }
        } catch (InterruptedException ignored) {
            Thread.currentThread().interrupt();
        }

        // fail situation
        curatorFramework.close();
        throw new RuntimeException("failed to connect to zookeeper service : " + url);
    }

    public static void closeWatch(List<String> watchs) {
        for (String watch : watchs) {
            closeWatch(watch);
        }
    }

    public static void closeWatch(String path) {
        PathChildrenCache childrenCache = watchMap.get(path);
        if (childrenCache != null) {
            try {
                childrenCache.close();
            } catch (IOException e) {
                throw new RuntimeException(e);
            }
        }
    }

View on GitHub (pinned to 65f8d8beb7)