{"record":{"id":"5ed722b7e14029e8","repo":"apache/dolphinscheduler","slug":"connect-to-host-host-failed","errorCode":null,"errorMessage":"connect to host: \" + host + \" failed","messagePattern":"connect to host: \" \\+ host \\+ \" failed","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/client/NettyRemotingClient.java","lineNumber":223,"sourceCode":"            channelsLock.unlock();\n        }\n        return channel;\n    }\n\n    /**\n     * create channel\n     *\n     * @param host host\n     * @return channel\n     */\n    Channel createChannel(Host host) {\n        try {\n            ChannelFuture future = bootstrap.connect(new InetSocketAddress(host.getIp(), host.getPort()));\n            future = future.sync();\n            if (future.isSuccess()) {\n                return future.channel();\n            } else {\n                throw new IllegalArgumentException(\"connect to host: \" + host + \" failed\", future.cause());\n            }\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            throw new RuntimeException(\"Connect to host: \" + host + \" failed\", e);\n        }\n    }\n\n    @Override\n    public void close() {\n        if (isStarted.compareAndSet(true, false)) {\n            try {\n                closeChannels();\n                if (workerGroup != null) {\n                    this.workerGroup.shutdownGracefully();\n                }\n                log.info(\"netty client closed\");\n            } catch (Exception ex) {\n                log.error(\"netty client close exception\", ex);","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/client/NettyRemotingClient.java#L205-L241","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the remote process is running and listening: ss -tlnp on the target host, or nc -zv <ip> <port> from the caller","Validate the ip:port stored in the registry matches the real worker address; fix host/port config if wrong","Open firewall/security-group rules for the DolphinScheduler RPC port","Inspect future.cause() (chained as the IllegalArgumentException cause) — ConnectException: Connection refused vs NoRouteToHostException point to different fixes","If in K8s/containers, verify service/DNS names resolve to the intended pod IP"],"exampleFix":"// before\nthrow new IllegalArgumentException(\"connect to host: \" + host + \" failed\", future.cause());\n// after\nif (!future.isSuccess()) {\n    log.error(\"Connect to {} failed: {}\", host, String.valueOf(future.cause()));\n    throw new IllegalArgumentException(\"connect to host: \" + host + \" failed\", future.cause());\n}","handlingStrategy":"try-catch","validationCode":"boolean isTargetUp(Host host) {\n    try (Socket s = new Socket()) {\n        s.connect(new InetSocketAddress(host.getIp(), host.getPort()), 2000);\n        return true;\n    } catch (IOException e) {\n        log.warn(\"Cannot reach {}: {}\", host, e.getMessage());\n        return false;\n    }\n}","typeGuard":"null","tryCatchPattern":"try {\n    return client.sendSync(host, request, timeout);\n} catch (RemoteException e) {\n    Throwable root = e.getCause();\n    if (root instanceof IllegalArgumentException\n            && root.getMessage() != null\n            && root.getMessage().startsWith(\"connect to host\")) {\n        // definitive connect failure: failover to another host, do not hot-retry same host\n        throw new UnreachableHostException(host, root);\n    }\n    throw e;\n}","preventionTips":["Health-check hosts (TCP probe) before adding them to the dispatch pool","Keep registry ip:port data authoritative and refreshed on process restart","Test connectivity after every firewall/security-group or network topology change","Log future.cause() to distinguish 'Connection refused' (process down) from 'No route to host' (network down)"],"tags":["network","connection-refused","netty","rpc"],"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"}