{"record":{"id":"535ae1a540d69435","repo":"apache/dolphinscheduler","slug":"worker-registry-client-start-up-error","errorCode":null,"errorMessage":"Worker registry client start up error","messagePattern":"Worker registry client start up error","errorType":"exception","errorClass":"RegistryException","httpStatus":null,"severity":"critical","filePath":"dolphinscheduler-worker/src/main/java/org/apache/dolphinscheduler/server/worker/registry/WorkerRegistryClient.java","lineNumber":85,"sourceCode":"\n    private WorkerHeartBeatTask workerHeartBeatTask;\n\n    @PostConstruct\n    public void initWorkRegistry() {\n        this.workerHeartBeatTask = new WorkerHeartBeatTask(\n                workerConfig,\n                workerServerLoadProtection,\n                metricsProvider,\n                registryClient,\n                physicalTaskExecutorContainerDelegator.getExecutorContainer());\n    }\n\n    public void start() {\n        try {\n            registry();\n            registryClient.addConnectionStateListener(new WorkerConnectionStateListener(registryClient));\n        } catch (Exception ex) {\n            throw new RegistryException(\"Worker registry client start up error\", ex);\n        }\n    }\n\n    private void registry() {\n        String workerRegistryPath = workerConfig.getWorkerRegistryPath();\n        // remove before persist\n        registryClient.remove(workerRegistryPath);\n        registryClient.persistEphemeral(workerRegistryPath, JSONUtils.toJsonString(workerHeartBeatTask.getHeartBeat()));\n        log.info(\"Worker node: {} registry to registry center {} successfully\", workerConfig.getWorkerAddress(),\n                workerRegistryPath);\n\n        while (!registryClient.checkNodeExists(workerConfig.getWorkerAddress(), RegistryNodeType.WORKER)) {\n            ThreadUtils.sleep(SLEEP_TIME_MILLIS);\n        }\n\n        workerHeartBeatTask.start();\n        log.info(\"Worker node: {} registry finished\", workerConfig.getWorkerAddress());\n    }","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-worker/src/main/java/org/apache/dolphinscheduler/server/worker/registry/WorkerRegistryClient.java#L67-L103","documentation":"WorkerRegistryClient.start() wraps registry() and connection-listener registration in a try/catch and rethrows any failure as a RegistryException. The worker could not register itself in the registry (ZooKeeper/etcd), so the master cannot discover it. The root cause is always in the chained cause exception.","triggerScenarios":"Calling WorkerRegistryClient.start() when registry() fails: registry client cannot connect, the worker registry path cannot be created/persisted, or addConnectionStateListener throws.","commonSituations":"ZooKeeper/etcd is down or unreachable (wrong registry plugin config), registry connect string/quorum misconfigured, auth/ACL issues on the registry path, network partition between worker and registry.","solutions":["Check the chained cause stack trace to find the real registry failure (connect timeout, session expired, etc.).","Verify registry plugin configuration (registry type, connect string, auth) in the worker's common/registry properties and that ZooKeeper/etcd is reachable.","Confirm the worker registry path (workerConfig.getWorkerRegistryPath()) is valid and the registry user has create/write permission on it.","Start the registry quorum and test connectivity (e.g. zkCli.sh) from the worker host, then restart the worker."],"exampleFix":"// before: registry unreachable, worker dies at start\nregistry.zookeeper.connect.string=localhost:2181 // zookeeper not running\n// after: point to a healthy reachable quorum\nregistry.zookeeper.connect.string=zk1:2181,zk2:2181,zk3:2181","handlingStrategy":"try-catch","validationCode":"// before start(): probe registry connectivity\ntry (CuratorFramework c = CuratorFrameworkFactory.newClient(connectString, new RetryNTimes(3, 1000))) {\n    c.start();\n    c.checkExists().forPath(\"/\");\n}","typeGuard":null,"tryCatchPattern":"try { workerRegistryClient.start(); } catch (RegistryException e) { log.error(\"Registry startup failed, cause={}\", e.getCause(), e); throw e; }","preventionTips":["Monitor ZooKeeper/etcd health and connectivity from worker hosts","Validate registry plugin config before deployment","Add connection-state alerting","Ensure registry path ACLs allow the worker user to create nodes"],"tags":["zookeeper","registry","startup","worker"],"backgroundTag":"connection-refused","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}