{"record":{"id":"7c951b36f85df543","repo":"apache/shenyu","slug":"failed-to-add-curator-cache-zookeeperclient","errorCode":null,"errorMessage":"failed to add curator cache.","messagePattern":"failed to add curator cache\\.","errorType":"exception","errorClass":"ShenyuException","httpStatus":null,"severity":"error","filePath":"shenyu-infra/shenyu-infra-zookeeper/src/main/java/org/apache/shenyu/infra/zookeeper/client/ZookeeperClient.java","lineNumber":302,"sourceCode":"\n    /**\n     * add new curator cache.\n     * @param path path.\n     * @param listeners listeners.\n     * @return cache.\n     */\n    public CuratorCache addCache(final String path, final CuratorCacheListener... listeners) {\n        CuratorCache cache = CuratorCache.build(client, path);\n        caches.put(path, cache);\n        if (ArrayUtils.isNotEmpty(listeners)) {\n            for (CuratorCacheListener listener : listeners) {\n                cache.listenable().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     * add new curator cache.\n     * @param path path.\n     * @param listeners listeners.\n     * @return cache.\n     */\n    public CuratorCache addCuratorCache(final String path, final CuratorCacheListener... listeners) {\n        return addCache(path, listeners);\n    }\n\n    /**\n     * add new tree cache.\n     * @param path path.\n     * @param listeners listeners.","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-infra/shenyu-infra-zookeeper/src/main/java/org/apache/shenyu/infra/zookeeper/client/ZookeeperClient.java#L284-L320","documentation":"ZookeeperClient.addCache starts a Curator (NodeCache/PathChildrenCache/TreeCache-family) cache after attaching listeners. If cache.start() throws any Exception, it is wrapped in ShenyuException('failed to add curator cache.') with the original cause attached. This usually means the Curator framework client is not started or the ZooKeeper session is unavailable.","triggerScenarios":"Calling addCache (via addCuratorCache) when the underlying CuratorFramework has not been started, or ZooKeeper is unreachable/session expired so cache.start() fails.","commonSituations":"ZooKeeper server down or wrong connection string, network/firewall blocking 2181, session timeout, calling addCache before client.start() during application startup ordering.","solutions":["Check the wrapped cause 'e' in logs for the real failure (connection refused, session timeout, etc.)","Verify ZooKeeper is reachable at the configured url (zkServer.sh status / nc -vz host 2181)","Ensure the Curator client is started before adding caches","Retry after re-establishing the ZooKeeper session"],"exampleFix":"// before\nzookeeperClient.addCache(path, false, listener); // client not started\n// after\nzookeeperClient.start();\nzookeeperClient.addCache(path, false, listener);","handlingStrategy":"try-catch","validationCode":"if (!zookeeperClient.isStarted()) { zookeeperClient.start(); }","typeGuard":null,"tryCatchPattern":"try {\n    zookeeperClient.addCache(path, dataIsCompressed, listener);\n} catch (ShenyuException e) {\n    log.error(\"curator cache start failed for path \" + path, e.getCause());\n    // retry after reconnecting the ZK session\n}","preventionTips":["Ensure ZooKeeper is reachable (host:2181) before startup","Start the Curator client before adding caches","Inspect the wrapped cause for the true failure","Add readiness checks on ZK before deploying the gateway"],"tags":["zookeeper","curator","cache"],"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"}