alibaba/druid · error · DruidRuntimeException

Please set the ZooKeeper node path.

Error message

Please set the ZooKeeper node path.

What it means

ZookeeperNodeListener.checkParameters() throws this when the ZooKeeper node path to watch is empty/null. The path is the znode whose children encode the HA node list (each child name -> host:port). Without it the PathChildrenCache and checkExists().forPath(path) calls have nothing to operate on, so Druid refuses to start the listener.

Source

Thrown at core/src/main/java/com/alibaba/druid/pool/ha/node/ZookeeperNodeListener.java:182

        lock.lock();
        try {
            Properties properties = getPropertiesFromCache();
            List<NodeEvent> events = NodeEvent.getEventsByDiffProperties(getProperties(), properties);
            if (events != null && !events.isEmpty()) {
                setProperties(properties);
            }
            return events;
        } finally {
            lock.unlock();
        }
    }

    private void checkParameters() {
        if (client == null && StringUtils.isEmpty(zkConnectString)) {
            throw new DruidRuntimeException("ZK Client is NULL, Please set the zkConnectString.");
        }
        if (StringUtils.isEmpty(path)) {
            throw new DruidRuntimeException("Please set the ZooKeeper node path.");
        }
        if (StringUtils.isEmpty(urlTemplate)) {
            throw new DruidRuntimeException("Please set the urlTemplate.");
        }
    }

    private void updateSingleNode(PathChildrenCacheEvent event, NodeEventTypeEnum type) {
        ChildData data = event.getData();
        String nodeName = getNodeName(data);
        List<String> names = new ArrayList<String>();
        names.add(getPrefix() + "." + nodeName);
        Properties properties = getPropertiesFromChildData(data);
        List<NodeEvent> events = NodeEvent.generateEvents(properties, names, type);

        if (events.isEmpty()) {
            return;
        }
        if (type == NodeEventTypeEnum.ADD) {

View on GitHub (pinned to fa8dc99126)

Solutions

1. Call listener.setPath("/your/znode") with the znode that contains one child per HA node.
2. Verify the znode exists in ZooKeeper (use zkCli `ls /your/znode`) and that the same path is configured.
3. Centralize HA config in one place to avoid divergent path values across environments.

Example fix

// before
ZookeeperNodeListener l = new ZookeeperNodeListener();
l.setZkConnectString("zk1:2181");
l.setUrlTemplate("jdbc:mysql://{host}:{port}/db");
l.start(); // throws: path missing

// after
l.setZkConnectString("zk1:2181");
l.setPath("/druid/ha/mysql");
l.setUrlTemplate("jdbc:mysql://{host}:{port}/db");
l.start();

ZookeeperNodeListener z = (ZookeeperNodeListener) listener;
if (z.getPath() == null || z.getPath().isEmpty()) {
    throw new IllegalStateException("set the ZooKeeper znode path via setPath(...)");
}

public static boolean pathConfigured(ZookeeperNodeListener z) {
    return z.getPath() != null && !z.getPath().isEmpty();
}

When it happens

Trigger: Starting a ZookeeperNodeListener whose path field is null or empty string — i.e. setPath(...) was never called or was passed an empty value.

Common situations: Config typo (e.g. property named basePath vs path); environment-specific config not loaded; copying example code without substituting the real znode path.

Related errors

• ZK Client is NULL, Please set the zkConnectString.
• Please set the urlTemplate.
• No Observer(such as PoolUpdater) specified.
• load managed jdbc driver event listener error. {filterName}
• ConfigLoader only support DruidDataSource

AI-assisted analysis of alibaba/druid@fa8dc99126 (2026-08-14). Data as JSON: /api/errors/15203a3f03e5bd91. Report an issue: GitHub.