{"record":{"id":"fa905fe6651ed696","repo":"apache/shenyu","slug":"failed-to-add-tree-cache","errorCode":null,"errorMessage":"failed to add tree cache.","messagePattern":"failed to add tree 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":336,"sourceCode":"     * add new tree cache.\n     * @param path path.\n     * @param listeners listeners.\n     * @return tree cache.\n     * @deprecated Use {@link #addCuratorCache(String, CuratorCacheListener...)} instead.\n     */\n    @Deprecated\n    public TreeCache addTreeCache(final String path, final TreeCacheListener... listeners) {\n        TreeCache cache = TreeCache.newBuilder(client, path).build();\n        treeCaches.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 tree cache.\", e);\n        }\n        return cache;\n    }\n\n    /**\n     * get created tree cache.\n     * @param path path.\n     * @return tree cache.\n     * @deprecated Use {@link #getCache(String)} instead.\n     */\n    @Deprecated\n    public TreeCache getTreeCache(final String path) {\n        return treeCaches.get(path);\n    }\n\n    /**\n     * add children watcher.\n     * @param key selectKey","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-infra/shenyu-infra-zookeeper/src/main/java/org/apache/shenyu/infra/zookeeper/client/ZookeeperClient.java#L318-L354","documentation":"ZookeeperClient.addTreeCache creates a Curator TreeCache for a path, attaches an optional listener, and starts it. If cache.start() throws, the exception is wrapped as ShenyuException('failed to add tree cache.'). Same root causes as curator cache start failures: connection problems or an unstarted client.","triggerScenarios":"Calling addTreeCache while ZooKeeper is unreachable or the CuratorFramework is not in STARTED state, causing TreeCache.start() to fail.","commonSituations":"ZooKeeper cluster down during gateway startup, wrong zookeeper url, session expiry, registering the tree cache too early in the startup lifecycle.","solutions":["Inspect the wrapped cause for the underlying error","Confirm the ZooKeeper connection string and that the server is up","Start the Curator client before calling addTreeCache","Re-add the cache after the session is re-established"],"exampleFix":"// before\nclient.addTreeCache(\"/shenyu/register\", listener); // ZK down\n// after\n// first ensure ZK is up and client started:\nzookeeperClient.start();\nzookeeperClient.addTreeCache(\"/shenyu/register\", listener);","handlingStrategy":"try-catch","validationCode":"if (!zookeeperClient.isStarted()) { zookeeperClient.start(); }\nif (zookeeperClient.isExistNode(path)) { /* proceed */ }","typeGuard":null,"tryCatchPattern":"try {\n    zookeeperClient.addTreeCache(path, listener);\n} catch (ShenyuException e) {\n    log.error(\"tree cache start failed for \" + path, e.getCause());\n}","preventionTips":["Verify ZK connectivity at startup","Do not add caches before client start","Monitor session expiry and re-register caches on reconnect"],"tags":["zookeeper","curator","tree-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"}