apache/dolphinscheduler · critical · RuntimeException

Connect to host: " + host + " failed

Error message

Connect to host: " + host + " failed

What it means

NettyRemotingClient.createChannel fails to establish a Netty channel to the remote host and wraps the underlying connect failure (future.cause()) in an IllegalArgumentException, or wraps an InterruptedException in a RuntimeException with the same message. It signals that the DolphinScheduler RPC client could not open a TCP connection to the target worker/api server address.

Source

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

    /**
     * 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. Verify the target host is reachable and the DolphinScheduler server is running on the configured port (telnet/nc host port)
  2. Check the wrapped future.cause() in the stack trace — connection refused vs unknown host tells you which fix applies
  3. Correct the host/port in the DolphinScheduler server/worker configuration
  4. Check firewall/security-group rules and DNS resolution for the host
  5. If caused by interruption, find and fix the code shutting down or interrupting the RPC client thread

Example fix

// before
NettyRemotingClient client = NettyRemotingClient.getInstance();
Channel channel = client.getChannel("192.168.1.50:1234");
// after
// ensure the worker is up and the address is correct first
NettyRemotingClient client = NettyRemotingClient.getInstance();
try (Channel channel = client.getChannel("192.168.1.50:1234")) {
    // use channel
}
Defensive patterns

Strategy: retry

Validate before calling

// pre-check reachability before RPC
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 3000);
} catch (IOException e) {
    throw new IllegalStateException("Server " + host + ":" + port + " unreachable: " + e.getMessage());
}

Try / catch

try {
    Channel ch = client.getChannel(host + ":" + port);
} catch (RuntimeException e) {
    if (e.getCause() instanceof ConnectException) {
        // retry with backoff / alert server is down
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling getOrCreateChannel -> createChannel for a host:port where the connect future completes unsuccessfully (connection refused, DNS failure, timeout) or the thread waiting on the connect future is interrupted.

Common situations: Target worker is down or not listening on the configured port; wrong host/port in server configuration; firewall or network partition blocking the port; DNS misconfiguration; the connecting thread is interrupted during shutdown.

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/6c583a860addbda8. Report an issue: GitHub.