{"record":{"id":"de8d2146b02fb129","repo":"apache/shenyu","slug":"failed-to-add-curator-cache","errorCode":null,"errorMessage":"failed to add curator cache.","messagePattern":"failed to add curator cache\\.","errorType":"exception","errorClass":"ShenyuException","httpStatus":null,"severity":"error","filePath":"shenyu-admin/src/main/java/org/apache/shenyu/admin/mode/cluster/impl/zookeeper/ClusterZookeeperClient.java","lineNumber":247,"sourceCode":"\n    /**\n     * add new curator cache.\n     * @param path path.\n     * @param listeners listeners.\n     * @return cache.\n     */\n    public TreeCache addCache(final String path, final TreeCacheListener... listeners) {\n        TreeCache cache = TreeCache.newBuilder(client, path).build();\n        caches.put(path, cache);\n        if (ArrayUtils.isNotEmpty(listeners)) {\n            for (TreeCacheListener listener : listeners) {\n                cache.getListenable().addListener(listener);\n            }\n        }\n        try {\n            cache.start();\n        } catch (Exception e) {\n            throw new ShenyuException(\"failed to add curator cache.\", e);\n        }\n        return cache;\n    }\n\n    /**\n     * find cache with  key.\n     * @param key key.\n     * @return cache.\n     */\n    private TreeCache findFromcache(final String key) {\n        for (Map.Entry<String, TreeCache> cache : caches.entrySet()) {\n            if (key.startsWith(cache.getKey())) {\n                return cache.getValue();\n            }\n        }\n        return null;\n    }\n}","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-admin/src/main/java/org/apache/shenyu/admin/mode/cluster/impl/zookeeper/ClusterZookeeperClient.java#L229-L265","documentation":"ClusterZookeeperClient.addCache builds a Curator TreeCache/NodeCache to watch zookeeper nodes for the ShenYu cluster mode. If cache.start() throws (typically because the zookeeper connection failed or the node is unavailable), the client wraps it in ShenyuException(\"failed to add curator cache.\"). This indicates the admin could not establish a watch on zookeeper.","triggerScenarios":"Calling addCache with a curator client whose zookeeper session is down — e.g. wrong zk address, zk unreachable, auth failure, session expired between client init and cache.start().","commonSituations":"Zookeeper cluster down or network partitioned; wrong shenyu.cluster.zookeeper url/connection config; zk auth (ACL) credentials missing; zk restarted while admin was starting; DNS/hostname resolution failure in containerized deployments.","solutions":["Verify zookeeper is reachable from admin: check the configured URL and test with `zkCli.sh -server host:2181`.","Inspect the wrapped cause `e` in logs — it names the real Curator/KeeperException (connection loss, no auth, session expired).","Fix connection/auth settings (shenyu cluster zookeeper url, session timeout, digest credentials) and restart admin.","Ensure zookeeper quorum is healthy (enough nodes up) and firewall rules allow admin:2181 traffic."],"exampleFix":"// before (application.yml)\nshenyu:\n  cluster:\n    zookeeper:\n      url: zk-inner:2181\n// after (correct reachable address + timeouts)\nshenyu:\n  cluster:\n    zookeeper:\n      url: zk-1:2181,zk-2:2181,zk-3:2181\n      sessionTimeout: 60000","handlingStrategy":"retry","validationCode":"try (CuratorFramework zk = client.getZkClient()) {\n    if (!zk.blockUntilConnected(10, TimeUnit.SECONDS))\n        throw new IllegalStateException(\"zookeeper not connected before adding cache\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    clusterZookeeperClient.addCache(path, listener);\n} catch (ShenyuException e) {\n    LOG.error(\"curator cache start failed, root cause: {}\", e.getCause(), e);\n    // retry with backoff\n}","preventionTips":["Verify zookeeper reachability before admin startup","Use multi-endpoint zk URLs for quorum resilience","Inspect e.getCause() — the Curator exception names the real failure","Set sane session/connection timeouts"],"tags":["zookeeper","curator","connection","cluster-mode"],"backgroundTag":"connection-refused","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}