apache/incubator-seata · error · IllegalStateException

Add nodeCache listener for path:%s

Error message

Add nodeCache listener for path:%s

What it means

ZookeeperConfiguration.addDataListener wraps any failure while building/starting a CuratorCache for a Zookeeper path into IllegalStateException with the message 'Add nodeCache listener for path:<path>'. It fires when a configuration listener is being attached (addConfigListener) and Curator throws — typically because the connection to Zookeeper is down or the curator client is in a bad state.

Source

Thrown at config/seata-config-zk/src/main/java/org/apache/seata/config/zk/ZookeeperConfiguration.java:460

                            .setDataId(dataId)
                            .setNewValue(o.toString())
                            .setChangeType(ConfigurationChangeType.MODIFY);
                    listener.onProcessEvent(event);
                }
            }
        }
    }

    protected void addDataListener(String path, NodeCacheListenerImpl nodeCacheListener) {
        try {
            CuratorCache nodeCache = CuratorCache.build(zkClient, path);
            if (nodeCacheMap.putIfAbsent(path, nodeCache) != null) {
                return;
            }
            nodeCache.listenable().addListener(nodeCacheListener);
            nodeCache.start();
        } catch (Exception e) {
            throw new IllegalStateException("Add nodeCache listener for path:" + path, e);
        }
    }

    protected void removeDataListener(String path, NodeCacheListenerImpl nodeCacheListener) {
        CuratorCache nodeCache = nodeCacheMap.get(path);
        if (nodeCache != null) {
            nodeCache.listenable().removeListener(nodeCacheListener);
        }
        nodeCacheListener.listener = null;
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

1. Verify Zookeeper is reachable: echo ruok | nc <zk-host> 2181 and check zk connection stats on the seata host
2. Correct config.zk.server-addr / cluster config so the Curator client connects successfully before listeners attach
3. Tune the Curator retry policy (e.g. ExponentialBackoffRetry with more attempts) so transient outages are absorbed instead of surfacing here
4. Restart seata-server after a ZK session storm; the IllegalStateException is not retryable in-place because nodeCacheMap may hold a half-registered cache

try { configuration.addConfigListener(dataId, listener); } catch (IllegalStateException e) { log.error("ZK listener attach failed for {}, retry after ZK recovery", dataId, e); scheduleReattach(dataId, listener); }

When it happens

Trigger: Calling addConfigListener during dynamic config subscription while the Zookeeper server is unreachable, the session has expired, the path is malformed, or the CuratorCache.start() races with connection loss. The catch(Exception) block converts Curator's ConnectionLossException/SessionExpiredException etc. into this ISE.

Common situations: Zookeeper outage or rolling restart while seata-server subscribes to config changes; network partition between seata and ZK; wrong zk address/namespace in config so the client cannot establish a session; retry policy exhaustion after a GC pause or network flap.

Related errors

• not support atomic operation putConfigIfAbsent
• ERR_CONFIG
• No JsonCodec provider found. Please add json-common-core to
• not found service provider for : {} caused by {}
• not found service provider for : {}

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/11ed06ea9f70d8eb. Report an issue: GitHub.