{"record":{"id":"27ae4613709794f9","repo":"apache/incubator-seata","slug":"connect-failed-can-not-connect-to-services-server","errorCode":null,"errorMessage":"connect failed, can not connect to services-server.","messagePattern":"connect failed, can not connect to services-server\\.","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientBootstrap.java","lineNumber":185,"sourceCode":"            LOGGER.error(\"Failed to shutdown: {}\", exx.getMessage());\n        }\n    }\n\n    /**\n     * Gets new channel.\n     *\n     * @param address the address\n     * @return the new channel\n     */\n    public Channel getNewChannel(InetSocketAddress address) {\n        Channel channel;\n        ChannelFuture f = this.bootstrap.connect(address);\n        try {\n            f.await(this.nettyClientConfig.getConnectTimeoutMillis(), TimeUnit.MILLISECONDS);\n            if (f.isCancelled()) {\n                throw new FrameworkException(f.cause(), \"connect cancelled, can not connect to services-server.\");\n            } else if (!f.isSuccess()) {\n                throw new FrameworkException(f.cause(), \"connect failed, can not connect to services-server.\");\n            } else {\n                channel = f.channel();\n            }\n\n            if (nettyClientConfig.getProtocol().equals(Protocol.GRPC.value)) {\n                Http2StreamChannelBootstrap bootstrap = new Http2StreamChannelBootstrap(channel);\n                bootstrap.handler(new ChannelInboundHandlerAdapter() {\n                    @Override\n                    public void handlerAdded(ChannelHandlerContext ctx) {\n                        Channel channel = ctx.channel();\n                        channel.pipeline()\n                                .addLast(new IdleStateHandler(\n                                        nettyClientConfig.getChannelMaxReadIdleSeconds(),\n                                        nettyClientConfig.getChannelMaxWriteIdleSeconds(),\n                                        nettyClientConfig.getChannelMaxAllIdleSeconds()));\n                        channel.pipeline().addLast(new GrpcDecoder());\n                        channel.pipeline().addLast(new GrpcEncoder());\n                        if (channelHandlers != null) {","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientBootstrap.java#L167-L203","documentation":"FrameworkException from NettyClientBootstrap.getNewChannel when the TCP connect to the seata server did not succeed within the connect timeout (f.isSuccess() false). The original connection failure is attached as the cause (connection refused, no route to host, timeout). This is the primary 'cannot reach the TC' error on channel creation.","triggerScenarios":"Any path that creates a client channel — TM/RM registration or reconnect — when the server address is unreachable: server down, wrong IP/port in the registry, firewall dropping SYNs, or connect timeout shorter than network RTT.","commonSituations":"seata-server not started or still booting when clients connect; registry (e.g. Nacos) returning stale instance IPs after server restart/scale-down; Docker/K8s network policies blocking the port; DNS resolution differences inside containers; connect timeout too small across high-latency links.","solutions":["Verify the seata-server process is up and listening on the advertised port (telnet/nc from the client host)","Check the registry instance list for stale/incorrect addresses and fix registration or wait for heartbeat expiry","Open/verify network path: firewall, security groups, k8s NetworkPolicy between client and server","Increase transport connect timeout if RTT is high (e.g. seata.client.rm.connect-timeout-millis / tm equivalent)"],"exampleFix":"# application.yml\nseata:\n  client:\n    tm:\n      connect-timeout-millis: 10000   # was 3000, too low for the network\n    rm:\n      connect-timeout-millis: 10000","handlingStrategy":"retry","validationCode":"// pre-connect reachability check (cheap, avoids exception path)\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(host, port), 2000);\n} catch (IOException ioe) {\n    // server unreachable: fix network before letting seata connect\n}","typeGuard":null,"tryCatchPattern":"catch (FrameworkException e) {\n    if (e.getMessage().contains(\"connect failed\")) {\n        Throwable cause = e.getCause(); // real reason: refused / timeout / no route\n        // schedule retry with backoff; alert if persistent\n    }\n}","preventionTips":["Verify server reachability before app startup (init probe)","Keep connect-timeout-millis >= 3x expected RTT","Monitor registry instance health to avoid connecting to dead addresses"],"tags":["network","connect","timeout","client"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}