{"record":{"id":"796742bac2f35208","repo":"apache/dolphinscheduler","slug":"failed-to-put-registry-key","errorCode":null,"errorMessage":"Failed to put registry key: ","messagePattern":"Failed to put registry key: ","errorType":"exception","errorClass":"RegistryException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-zookeeper/src/main/java/org/apache/dolphinscheduler/plugin/registry/zookeeper/ZookeeperRegistry.java","lineNumber":182,"sourceCode":"        try {\n            return null != client.checkExists().forPath(key);\n        } catch (Exception e) {\n            throw new RegistryException(\"zookeeper check key is existed error\", e);\n        }\n    }\n\n    @Override\n    public void put(String key, String value, boolean deleteOnDisconnect) {\n        final CreateMode mode = deleteOnDisconnect ? CreateMode.EPHEMERAL : CreateMode.PERSISTENT;\n\n        try {\n            client.create()\n                    .orSetData()\n                    .creatingParentsIfNeeded()\n                    .withMode(mode)\n                    .forPath(key, value.getBytes(StandardCharsets.UTF_8));\n        } catch (Exception e) {\n            throw new RegistryException(\"Failed to put registry key: \" + key, e);\n        }\n    }\n\n    @Override\n    public List<String> children(String key) {\n        try {\n            List<String> result = client.getChildren().forPath(key);\n            result.sort(Comparator.reverseOrder());\n            return result;\n        } catch (Exception e) {\n            throw new RegistryException(\"zookeeper get children error\", e);\n        }\n    }\n\n    @Override\n    public void delete(String nodePath) {\n        try {\n            client.delete()","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-zookeeper/src/main/java/org/apache/dolphinscheduler/plugin/registry/zookeeper/ZookeeperRegistry.java#L164-L200","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the wrapped cause code: CONNECTIONLOSS/SESSIONEXPIRED → restore session and retry the put","Check ACLs allow create/write for the client on the key and its parent chain","Verify the key path is absolute and well-formed (no empty segments from null/empty IDs)","Check ensemble health and ZooKeeper limits (znode 1MB data limit, read-only mode, disk quota)","For registration-style keys, ensure only one instance writes the same ephemeral path or that deleteOnDisconnect/session semantics are as intended"],"exampleFix":"// before\nregistry.put(\"/lock/\" + name, data, true);\n// after\nif (name == null || name.contains(\"/\")) { throw new IllegalArgumentException(\"invalid lock name\"); }\nregistry.put(\"/lock/\" + name, data, true);","handlingStrategy":"retry","validationCode":"if (key == null || !key.startsWith(\"/\") || key.split(\"/\").length < 2) {\n    throw new IllegalArgumentException(\"invalid registry key: \" + key);\n}\nif (value != null && value.getBytes(StandardCharsets.UTF_8).length > 1_000_000) {\n    throw new IllegalArgumentException(\"value exceeds ZooKeeper 1MB znode limit\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    registry.put(key, value, deleteOnDisconnect);\n} catch (RegistryException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof KeeperException.ConnectionLossException\n            || cause instanceof KeeperException.SessionExpiredException) {\n        retryPut(key, value, deleteOnDisconnect); // idempotent create-or-set makes retry safe\n    } else {\n        throw e;\n    }\n}","preventionTips":["Keep znode values small (<1MB); store large data elsewhere and keep a reference in ZooKeeper","Check ACLs on parent paths so create with creatingParentsIfNeeded succeeds","Make puts idempotent — orSetData semantics allow safe retries after connection loss","Monitor ensemble read-only/disk-quota states that silently reject writes"],"tags":["zookeeper","curator","registry","write-failed"],"backgroundTag":"database-write-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}