apache/shenyu · error · ShenyuException

failed to add curator cache.

Error message

failed to add curator cache.

What it means

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.

Solutions

1. Verify zookeeper is reachable from admin: check the configured URL and test with `zkCli.sh -server host:2181`.
2. Inspect the wrapped cause `e` in logs — it names the real Curator/KeeperException (connection loss, no auth, session expired).
3. Fix connection/auth settings (shenyu cluster zookeeper url, session timeout, digest credentials) and restart admin.
4. Ensure zookeeper quorum is healthy (enough nodes up) and firewall rules allow admin:2181 traffic.

Example fix

// before (application.yml)
shenyu:
  cluster:
    zookeeper:
      url: zk-inner:2181
// after (correct reachable address + timeouts)
shenyu:
  cluster:
    zookeeper:
      url: zk-1:2181,zk-2:2181,zk-3:2181
      sessionTimeout: 60000

try (CuratorFramework zk = client.getZkClient()) {
    if (!zk.blockUntilConnected(10, TimeUnit.SECONDS))
        throw new IllegalStateException("zookeeper not connected before adding cache");
}

try {
    clusterZookeeperClient.addCache(path, listener);
} catch (ShenyuException e) {
    LOG.error("curator cache start failed, root cause: {}", e.getCause(), e);
    // retry with backoff
}

When it happens

Trigger: 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().

Common situations: 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.

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
• zookeeper url: is is error.

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

Appendix: source

Thrown at shenyu-admin/src/main/java/org/apache/shenyu/admin/mode/cluster/impl/zookeeper/ClusterZookeeperClient.java:247

    /**
     * add new curator cache.
     * @param path path.
     * @param listeners listeners.
     * @return cache.
     */
    public TreeCache addCache(final String path, final TreeCacheListener... listeners) {
        TreeCache cache = TreeCache.newBuilder(client, path).build();
        caches.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 curator cache.", e);
        }
        return cache;
    }

    /**
     * find cache with  key.
     * @param key key.
     * @return cache.
     */
    private TreeCache findFromcache(final String key) {
        for (Map.Entry<String, TreeCache> cache : caches.entrySet()) {
            if (key.startsWith(cache.getKey())) {
                return cache.getValue();
            }
        }
        return null;
    }
}

View on GitHub (pinned to 567142e072)