alibaba/Sentinel · error · IllegalStateException

Zookeeper has not been initialized or error occurred

Error message

Zookeeper has not been initialized or error occurred

What it means

Thrown by ZookeeperDataSource.readSource() when the internal CuratorFramework zkClient is null. Like the Nacos/Redis data sources, init errors during listener setup are caught and only logged (RecordLog.warn + printStackTrace), so a failed ZooKeeper connection leaves zkClient null and every later read throws this IllegalStateException.

Source

Thrown at sentinel-extension/sentinel-datasource-zookeeper/src/main/java/com/alibaba/csp/sentinel/datasource/zookeeper/ZookeeperDataSource.java:159

                    } else {
                        this.zkClient = zkClientMap.get(zkKey);
                    }
                }
            }

            this.nodeCache = CuratorCache.build(this.zkClient, this.path);
            this.nodeCache.listenable().addListener(this.listener, this.pool);
            this.nodeCache.start();
        } catch (Exception e) {
            RecordLog.warn("[ZookeeperDataSource] Error occurred when initializing Zookeeper data source", e);
            e.printStackTrace();
        }
    }

    @Override
    public String readSource() throws Exception {
        if (this.zkClient == null) {
            throw new IllegalStateException("Zookeeper has not been initialized or error occurred");
        }
        String configInfo = null;
        ChildData childData = nodeCache.get(path).orElse(null);
        if (null != childData && childData.getData() != null) {

            configInfo = new String(childData.getData());
        }
        return configInfo;
    }

    @Override
    public void close() throws Exception {
        if (this.nodeCache != null) {
            this.nodeCache.listenable().removeListener(listener);
            this.nodeCache.close();
        }
        if (this.zkClient != null) {
            this.zkClient.close();

View on GitHub (pinned to a3f40ba8e9)

Solutions

  1. Look for '[ZookeeperDataSource] Error occurred when initializing Zookeeper data source' in the logs — the printed cause shows the real connection/auth problem.
  2. Verify ZooKeeper reachability: echo ruok | nc zk-host 2181 and zkCli.sh -server zk-host:2181 ls <path>.
  3. Fix serverAddr / AuthInfo credentials and restart the application; the client is not retried after a failed init.
  4. Optionally build and start the CuratorFramework yourself first (zkClient.blockUntilConnectedOrTimedOut()) so failures abort startup with a clear error.

Example fix

// before
new ZookeeperDataSource<>("bad-host:2181", path, parser); // init fails silently, readSource() throws

// after
CuratorFramework c = CuratorFrameworkFactory.newClient("zk.prod:2181", new RetryNTimes(3, 1000));
c.start();
c.blockUntilConnectedOrTimedOut();   // fail fast at boot if ZooKeeper is down
new ZookeeperDataSource<>("zk.prod:2181", path, parser);
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-verify ZooKeeper connectivity before creating the data source
CuratorFramework probe = CuratorFrameworkFactory.newClient(serverAddr, new RetryNTimes(3, 1000));
probe.start();
if (!probe.blockUntilConnected(5, TimeUnit.SECONDS)) {
    throw new IllegalStateException("cannot connect to ZooKeeper: " + serverAddr);
}
new ZookeeperDataSource<>(serverAddr, path, parser);

Try / catch

try {
    String raw = dataSource.loadConfig();
} catch (Exception e) {
    if (e instanceof IllegalStateException && e.getMessage().contains("not been initialized")) {
        log.error("Curator client failed to init; check serverAddr/auth and restart", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: ZooKeeper unreachable or the address wrong when initZookeeperListener() runs (Curator start fails), auth failure with digest auth, or Curator/JDK version incompatibility — the cause is swallowed, then loadInitialConfig()/readSource() throws this error.

Common situations: ZooKeeper quorum down at app startup; wrong serverAddr (port 2181 vs 26381); ACL-protected znodes with bad AuthInfo; network partitions in Kubernetes. The app runs but the refresh thread repeatedly logs this exception and rules never load.

Related errors

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/e04d4941bae93f9f. Report an issue: GitHub.