apache/dolphinscheduler · error · IllegalArgumentException

connect to host: " + host + " failed

Error message

connect to host: " + host + " failed

What it means

createChannel attempts a Netty bootstrap.connect to the host and throws IllegalArgumentException("connect to host: ... failed") when the connect future completes but isSuccess() is false, i.e. the TCP connection attempt definitively failed. Being an unchecked IllegalArgumentException, it propagates up through getOrCreateChannel into doSendSync/sendSync where it is re-wrapped as a RemoteException.

Source

Thrown at dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/client/NettyRemotingClient.java:223

            channelsLock.unlock();
        }
        return channel;
    }

    /**
     * create channel
     *
     * @param host host
     * @return channel
     */
    Channel createChannel(Host host) {
        try {
            ChannelFuture future = bootstrap.connect(new InetSocketAddress(host.getIp(), host.getPort()));
            future = future.sync();
            if (future.isSuccess()) {
                return future.channel();
            } else {
                throw new IllegalArgumentException("connect to host: " + host + " failed", future.cause());
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RuntimeException("Connect to host: " + host + " failed", e);
        }
    }

    @Override
    public void close() {
        if (isStarted.compareAndSet(true, false)) {
            try {
                closeChannels();
                if (workerGroup != null) {
                    this.workerGroup.shutdownGracefully();
                }
                log.info("netty client closed");
            } catch (Exception ex) {
                log.error("netty client close exception", ex);

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Check the remote process is running and listening: ss -tlnp on the target host, or nc -zv <ip> <port> from the caller
  2. Validate the ip:port stored in the registry matches the real worker address; fix host/port config if wrong
  3. Open firewall/security-group rules for the DolphinScheduler RPC port
  4. Inspect future.cause() (chained as the IllegalArgumentException cause) — ConnectException: Connection refused vs NoRouteToHostException point to different fixes
  5. If in K8s/containers, verify service/DNS names resolve to the intended pod IP

Example fix

// before
throw new IllegalArgumentException("connect to host: " + host + " failed", future.cause());
// after
if (!future.isSuccess()) {
    log.error("Connect to {} failed: {}", host, String.valueOf(future.cause()));
    throw new IllegalArgumentException("connect to host: " + host + " failed", future.cause());
}
Defensive patterns

Strategy: try-catch

Validate before calling

boolean isTargetUp(Host host) {
    try (Socket s = new Socket()) {
        s.connect(new InetSocketAddress(host.getIp(), host.getPort()), 2000);
        return true;
    } catch (IOException e) {
        log.warn("Cannot reach {}: {}", host, e.getMessage());
        return false;
    }
}

Type guard

null

Try / catch

try {
    return client.sendSync(host, request, timeout);
} catch (RemoteException e) {
    Throwable root = e.getCause();
    if (root instanceof IllegalArgumentException
            && root.getMessage() != null
            && root.getMessage().startsWith("connect to host")) {
        // definitive connect failure: failover to another host, do not hot-retry same host
        throw new UnreachableHostException(host, root);
    }
    throw e;
}

Prevention

When it happens

Trigger: getOrCreateChannel -> createChannel: no active cached channel exists, so a new connection is made; the connect completes unsuccessfully — connection refused (nothing listening), host unreachable, or the sync() detected failure — and future.isSuccess() is false.

Common situations: Worker/master not started or crashed; wrong IP/port in registry config; firewalled port; container network misconfiguration (wrong service name/port in K8s); IPv4/IPv6 mismatch resolving the host address.

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

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