apache/shenyu · error · ShenyuException

failed to add tree cache.

Error message

failed to add tree cache.

What it means

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.

Solutions

1. Inspect the wrapped cause for the underlying error
2. Confirm the ZooKeeper connection string and that the server is up
3. Start the Curator client before calling addTreeCache
4. Re-add the cache after the session is re-established

Example fix

// before
client.addTreeCache("/shenyu/register", listener); // ZK down
// after
// first ensure ZK is up and client started:
zookeeperClient.start();
zookeeperClient.addTreeCache("/shenyu/register", listener);

if (!zookeeperClient.isStarted()) { zookeeperClient.start(); }
if (zookeeperClient.isExistNode(path)) { /* proceed */ }

try {
    zookeeperClient.addTreeCache(path, listener);
} catch (ShenyuException e) {
    log.error("tree cache start failed for " + path, e.getCause());
}

When it happens

Trigger: Calling addTreeCache while ZooKeeper is unreachable or the CuratorFramework is not in STARTED state, causing TreeCache.start() to fail.

Common situations: ZooKeeper cluster down during gateway startup, wrong zookeeper url, session expiry, registering the tree cache too early in the startup lifecycle.

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

• failed to add curator cache.
• failed to add curator cache.
• renew master fail
• zookeeper url is empty
• zookeeper url: is is error.

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/fa905fe6651ed696. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-infra/shenyu-infra-zookeeper/src/main/java/org/apache/shenyu/infra/zookeeper/client/ZookeeperClient.java:336

     * add new tree cache.
     * @param path path.
     * @param listeners listeners.
     * @return tree cache.
     * @deprecated Use {@link #addCuratorCache(String, CuratorCacheListener...)} instead.
     */
    @Deprecated
    public TreeCache addTreeCache(final String path, final TreeCacheListener... listeners) {
        TreeCache cache = TreeCache.newBuilder(client, path).build();
        treeCaches.put(path, cache);
        if (ArrayUtils.isNotEmpty(listeners)) {
            for (TreeCacheListener listener : listeners) {
                cache.getListenable().addListener(listener);
            }
        }
        try {
            cache.start();
        } catch (Exception e) {
            throw new ShenyuException("failed to add tree cache.", e);
        }
        return cache;
    }

    /**
     * get created tree cache.
     * @param path path.
     * @return tree cache.
     * @deprecated Use {@link #getCache(String)} instead.
     */
    @Deprecated
    public TreeCache getTreeCache(final String path) {
        return treeCaches.get(path);
    }

    /**
     * add children watcher.
     * @param key selectKey

View on GitHub (pinned to 567142e072)