apache/shenyu · error · ShenyuException

failed to add curator cache.

Error message

failed to add curator cache.

What it means

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.

Solutions

1. Check the wrapped cause 'e' in logs for the real failure (connection refused, session timeout, etc.)
2. Verify ZooKeeper is reachable at the configured url (zkServer.sh status / nc -vz host 2181)
3. Ensure the Curator client is started before adding caches
4. Retry after re-establishing the ZooKeeper session

Example fix

// before
zookeeperClient.addCache(path, false, listener); // client not started
// after
zookeeperClient.start();
zookeeperClient.addCache(path, false, listener);

if (!zookeeperClient.isStarted()) { zookeeperClient.start(); }

try {
    zookeeperClient.addCache(path, dataIsCompressed, listener);
} catch (ShenyuException e) {
    log.error("curator cache start failed for path " + path, e.getCause());
    // retry after reconnecting the ZK session
}

When it happens

Trigger: Calling addCache (via addCuratorCache) when the underlying CuratorFramework has not been started, or ZooKeeper is unreachable/session expired so cache.start() fails.

Common situations: ZooKeeper server down or wrong connection string, network/firewall blocking 2181, session timeout, calling addCache before client.start() during application startup ordering.

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 tree cache.
• renew master fail
• zookeeper url is empty
• Decrement when domain ssl counts <= 0, an unknown exception…

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

Appendix: source

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

    /**
     * add new curator cache.
     * @param path path.
     * @param listeners listeners.
     * @return cache.
     */
    public CuratorCache addCache(final String path, final CuratorCacheListener... listeners) {
        CuratorCache cache = CuratorCache.build(client, path);
        caches.put(path, cache);
        if (ArrayUtils.isNotEmpty(listeners)) {
            for (CuratorCacheListener listener : listeners) {
                cache.listenable().addListener(listener);
            }
        }
        try {
            cache.start();
        } catch (Exception e) {
            throw new ShenyuException("failed to add curator cache.", e);
        }
        return cache;
    }

    /**
     * add new curator cache.
     * @param path path.
     * @param listeners listeners.
     * @return cache.
     */
    public CuratorCache addCuratorCache(final String path, final CuratorCacheListener... listeners) {
        return addCache(path, listeners);
    }

    /**
     * add new tree cache.
     * @param path path.
     * @param listeners listeners.

View on GitHub (pinned to 567142e072)