apache/dolphinscheduler · critical · RegistryException

Worker registry client start up error

Error message

Worker registry client start up error

What it means

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.

Source

Thrown at dolphinscheduler-worker/src/main/java/org/apache/dolphinscheduler/server/worker/registry/WorkerRegistryClient.java:85

    private WorkerHeartBeatTask workerHeartBeatTask;

    @PostConstruct
    public void initWorkRegistry() {
        this.workerHeartBeatTask = new WorkerHeartBeatTask(
                workerConfig,
                workerServerLoadProtection,
                metricsProvider,
                registryClient,
                physicalTaskExecutorContainerDelegator.getExecutorContainer());
    }

    public void start() {
        try {
            registry();
            registryClient.addConnectionStateListener(new WorkerConnectionStateListener(registryClient));
        } catch (Exception ex) {
            throw new RegistryException("Worker registry client start up error", ex);
        }
    }

    private void registry() {
        String workerRegistryPath = workerConfig.getWorkerRegistryPath();
        // remove before persist
        registryClient.remove(workerRegistryPath);
        registryClient.persistEphemeral(workerRegistryPath, JSONUtils.toJsonString(workerHeartBeatTask.getHeartBeat()));
        log.info("Worker node: {} registry to registry center {} successfully", workerConfig.getWorkerAddress(),
                workerRegistryPath);

        while (!registryClient.checkNodeExists(workerConfig.getWorkerAddress(), RegistryNodeType.WORKER)) {
            ThreadUtils.sleep(SLEEP_TIME_MILLIS);
        }

        workerHeartBeatTask.start();
        log.info("Worker node: {} registry finished", workerConfig.getWorkerAddress());
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Check the chained cause stack trace to find the real registry failure (connect timeout, session expired, etc.).
2. Verify registry plugin configuration (registry type, connect string, auth) in the worker's common/registry properties and that ZooKeeper/etcd is reachable.
3. Confirm the worker registry path (workerConfig.getWorkerRegistryPath()) is valid and the registry user has create/write permission on it.
4. Start the registry quorum and test connectivity (e.g. zkCli.sh) from the worker host, then restart the worker.

Example fix

// before: registry unreachable, worker dies at start
registry.zookeeper.connect.string=localhost:2181 // zookeeper not running
// after: point to a healthy reachable quorum
registry.zookeeper.connect.string=zk1:2181,zk2:2181,zk3:2181

// before start(): probe registry connectivity
try (CuratorFramework c = CuratorFrameworkFactory.newClient(connectString, new RetryNTimes(3, 1000))) {
    c.start();
    c.checkExists().forPath("/");
}

try { workerRegistryClient.start(); } catch (RegistryException e) { log.error("Registry startup failed, cause={}", e.getCause(), e); throw e; }

When it happens

Trigger: Calling WorkerRegistryClient.start() when registry() fails: registry client cannot connect, the worker registry path cannot be created/persisted, or addConnectionStateListener throws.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• zookeeper connect failed to: in : ms
• Zookeeper registry start failed
• Cannot connect to registry in %s s
• Failed to subscribe listener for key:
• zookeeper get data error

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