{"record":{"id":"11ed06ea9f70d8eb","repo":"apache/incubator-seata","slug":"add-nodecache-listener-for-path-s","errorCode":null,"errorMessage":"Add nodeCache listener for path:%s","messagePattern":"Add nodeCache listener for path:(.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"config/seata-config-zk/src/main/java/org/apache/seata/config/zk/ZookeeperConfiguration.java","lineNumber":460,"sourceCode":"                            .setDataId(dataId)\n                            .setNewValue(o.toString())\n                            .setChangeType(ConfigurationChangeType.MODIFY);\n                    listener.onProcessEvent(event);\n                }\n            }\n        }\n    }\n\n    protected void addDataListener(String path, NodeCacheListenerImpl nodeCacheListener) {\n        try {\n            CuratorCache nodeCache = CuratorCache.build(zkClient, path);\n            if (nodeCacheMap.putIfAbsent(path, nodeCache) != null) {\n                return;\n            }\n            nodeCache.listenable().addListener(nodeCacheListener);\n            nodeCache.start();\n        } catch (Exception e) {\n            throw new IllegalStateException(\"Add nodeCache listener for path:\" + path, e);\n        }\n    }\n\n    protected void removeDataListener(String path, NodeCacheListenerImpl nodeCacheListener) {\n        CuratorCache nodeCache = nodeCacheMap.get(path);\n        if (nodeCache != null) {\n            nodeCache.listenable().removeListener(nodeCacheListener);\n        }\n        nodeCacheListener.listener = null;\n    }\n}\n","sourceCodeStart":442,"sourceCodeEnd":472,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/config/seata-config-zk/src/main/java/org/apache/seata/config/zk/ZookeeperConfiguration.java#L442-L472","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify Zookeeper is reachable: echo ruok | nc <zk-host> 2181 and check zk connection stats on the seata host","Correct config.zk.server-addr / cluster config so the Curator client connects successfully before listeners attach","Tune the Curator retry policy (e.g. ExponentialBackoffRetry with more attempts) so transient outages are absorbed instead of surfacing here","Restart seata-server after a ZK session storm; the IllegalStateException is not retryable in-place because nodeCacheMap may hold a half-registered cache"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { configuration.addConfigListener(dataId, listener); } catch (IllegalStateException e) { log.error(\"ZK listener attach failed for {}, retry after ZK recovery\", dataId, e); scheduleReattach(dataId, listener); }","preventionTips":["Ensure ZK connectivity and a started Curator client before subscribing listeners","Configure a bounded ExponentialBackoffRetry on the Curator client","Clean up listeners on shutdown so nodeCacheMap stays consistent","Monitor ZK session metrics to catch expiry storms early"],"tags":["seata","zookeeper","listener","connectivity"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}