apache/dolphinscheduler · error · RegistryException

Failed to put registry key:

Error message

Failed to put registry key: 

What it means

ZookeeperRegistry.put() creates or overwrites a ZNode with client.create().orSetData().creatingParentsIfNeeded().withMode(mode).forPath(key, value) and wraps any failure in a RegistryException ('Failed to put registry key: ' + key). Failures include connectivity loss, no RWACL permission, and node/children version conflicts during the create-or-set operation.

Source

Thrown at dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-zookeeper/src/main/java/org/apache/dolphinscheduler/plugin/registry/zookeeper/ZookeeperRegistry.java:182

        try {
            return null != client.checkExists().forPath(key);
        } catch (Exception e) {
            throw new RegistryException("zookeeper check key is existed error", e);
        }
    }

    @Override
    public void put(String key, String value, boolean deleteOnDisconnect) {
        final CreateMode mode = deleteOnDisconnect ? CreateMode.EPHEMERAL : CreateMode.PERSISTENT;

        try {
            client.create()
                    .orSetData()
                    .creatingParentsIfNeeded()
                    .withMode(mode)
                    .forPath(key, value.getBytes(StandardCharsets.UTF_8));
        } catch (Exception e) {
            throw new RegistryException("Failed to put registry key: " + key, e);
        }
    }

    @Override
    public List<String> children(String key) {
        try {
            List<String> result = client.getChildren().forPath(key);
            result.sort(Comparator.reverseOrder());
            return result;
        } catch (Exception e) {
            throw new RegistryException("zookeeper get children error", e);
        }
    }

    @Override
    public void delete(String nodePath) {
        try {
            client.delete()

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Check the wrapped cause code: CONNECTIONLOSS/SESSIONEXPIRED → restore session and retry the put
2. Check ACLs allow create/write for the client on the key and its parent chain
3. Verify the key path is absolute and well-formed (no empty segments from null/empty IDs)
4. Check ensemble health and ZooKeeper limits (znode 1MB data limit, read-only mode, disk quota)
5. For registration-style keys, ensure only one instance writes the same ephemeral path or that deleteOnDisconnect/session semantics are as intended

Example fix

// before
registry.put("/lock/" + name, data, true);
// after
if (name == null || name.contains("/")) { throw new IllegalArgumentException("invalid lock name"); }
registry.put("/lock/" + name, data, true);

if (key == null || !key.startsWith("/") || key.split("/").length < 2) {
    throw new IllegalArgumentException("invalid registry key: " + key);
}
if (value != null && value.getBytes(StandardCharsets.UTF_8).length > 1_000_000) {
    throw new IllegalArgumentException("value exceeds ZooKeeper 1MB znode limit");
}

try {
    registry.put(key, value, deleteOnDisconnect);
} catch (RegistryException e) {
    Throwable cause = e.getCause();
    if (cause instanceof KeeperException.ConnectionLossException
            || cause instanceof KeeperException.SessionExpiredException) {
        retryPut(key, value, deleteOnDisconnect); // idempotent create-or-set makes retry safe
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling put(key, value, deleteOnDisconnect) when the session is expired or connection lost (CONNECTIONLOSS), when ACLs deny create/write on the path, when the znode exists as ephemeral and children conflict with creatingParentsIfNeeded, or when the key is malformed (BADARGUMENTS).

Common situations: ZooKeeper disk quota or ensemble in read-only mode rejecting writes; permission-denied after locking down ACLs; two components racing to create the same ephemeral node (e.g. server registration duplicates) leading to NODEEXISTS without orSetData matching; keys containing slashes/empty segments due to ID interpolation.

Related errors

• Failed to subscribe listener for key:
• zookeeper get data error
• zookeeper check key is existed error
• zookeeper get children error
• Worker registry client start up error

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/796742bac2f35208. Report an issue: GitHub.