apache/dolphinscheduler · error · RegistryException

Cannot connect to registry in %s s

Error message

Cannot connect to registry in %s s

What it means

Thrown by ZookeeperRegistry.connectUntilTimeout(Duration) when the Curator client is still not connected after the given timeout elapses. The message contains the timeout in seconds. The original RegistryException is rethrown as-is; no cause is attached in this branch.

Source

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

            }
            stopWatch.stop();
            log.info("ZookeeperRegistry started at: {}/ms", stopWatch.getTime());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RegistryException("Zookeeper registry start failed", e);
        }
    }

    @Override
    public void addConnectionStateListener(ConnectionListener listener) {
        client.getConnectionStateListenable().addListener(new ZookeeperConnectionStateListener(listener));
    }

    @Override
    public void connectUntilTimeout(@NonNull Duration timeout) throws RegistryException {
        try {
            if (!client.blockUntilConnected(DurationUtils.toMillisInt(timeout), MILLISECONDS)) {
                throw new RegistryException(
                        String.format("Cannot connect to registry in %s s", timeout.getSeconds()));
            }
        } catch (RegistryException e) {
            throw e;
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RegistryException(
                    String.format("Cannot connect to registry in %s s", timeout.getSeconds()), e);
        }
    }

    @Override
    public void subscribe(final String path, final SubscribeListener listener) {
        final TreeCache treeCache = treeCacheMap.computeIfAbsent(path, $ -> new TreeCache(client, path));
        treeCache.getListenable().addListener(new ZookeeperTreeCacheListenerAdapter(path, listener));
        try {
            treeCache.start();
        } catch (Exception e) {

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify ZooKeeper connectivity (host:port) and that the ensemble is serving
  2. Increase the timeout passed to connectUntilTimeout
  3. Add connection-state listeners and retry logic with backoff around connectUntilTimeout
  4. Check network/DNS/firewall between client and ensemble
  5. Ensure the client was start()-ed before waiting on connectUntilTimeout

Example fix

// before
registry.connectUntilTimeout(Duration.ofSeconds(5));
// after
registry.connectUntilTimeout(Duration.ofSeconds(60));
Defensive patterns

Strategy: try-catch

Validate before calling

if (!zookeeperReachable(connectString)) {
    throw new IllegalStateException("ZooKeeper unreachable, skipping connectUntilTimeout");
}

Type guard

boolean zookeeperReachable(String connectString) {
    return Arrays.stream(connectString.split(","))
        .allMatch(hp -> {
            String[] p = hp.trim().split(":");
            try (Socket s = new Socket()) {
                s.connect(new InetSocketAddress(p[0], Integer.parseInt(p[1])), 3000);
                return true;
            } catch (IOException e) { return false; }
        });
}

Try / catch

try {
    registry.connectUntilTimeout(Duration.ofSeconds(60));
} catch (RegistryException e) {
    log.error("ZooKeeper not connected within timeout");
    // retry with backoff or fail fast
}

Prevention

When it happens

Trigger: Calling connectUntilTimeout(timeout) on a registry whose Curator client cannot reach the ZooKeeper ensemble within that duration (servers down, wrong connect string, network partition).

Common situations: ZooKeeper quorum unavailable at startup; misconfigured connect string after environment migration; slow network or overloaded ensemble exceeding a short timeout; startup sequencing expecting a sidecar not yet ready.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

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