apache/incubator-seata · critical · FrameworkException

connect failed, can not connect to services-server.

Error message

connect failed, can not connect to services-server.

What it means

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.

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientBootstrap.java:185

            LOGGER.error("Failed to shutdown: {}", exx.getMessage());
        }
    }

    /**
     * Gets new channel.
     *
     * @param address the address
     * @return the new channel
     */
    public Channel getNewChannel(InetSocketAddress address) {
        Channel channel;
        ChannelFuture f = this.bootstrap.connect(address);
        try {
            f.await(this.nettyClientConfig.getConnectTimeoutMillis(), TimeUnit.MILLISECONDS);
            if (f.isCancelled()) {
                throw new FrameworkException(f.cause(), "connect cancelled, can not connect to services-server.");
            } else if (!f.isSuccess()) {
                throw new FrameworkException(f.cause(), "connect failed, can not connect to services-server.");
            } else {
                channel = f.channel();
            }

            if (nettyClientConfig.getProtocol().equals(Protocol.GRPC.value)) {
                Http2StreamChannelBootstrap bootstrap = new Http2StreamChannelBootstrap(channel);
                bootstrap.handler(new ChannelInboundHandlerAdapter() {
                    @Override
                    public void handlerAdded(ChannelHandlerContext ctx) {
                        Channel channel = ctx.channel();
                        channel.pipeline()
                                .addLast(new IdleStateHandler(
                                        nettyClientConfig.getChannelMaxReadIdleSeconds(),
                                        nettyClientConfig.getChannelMaxWriteIdleSeconds(),
                                        nettyClientConfig.getChannelMaxAllIdleSeconds()));
                        channel.pipeline().addLast(new GrpcDecoder());
                        channel.pipeline().addLast(new GrpcEncoder());
                        if (channelHandlers != null) {

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Verify the seata-server process is up and listening on the advertised port (telnet/nc from the client host)
  2. Check the registry instance list for stale/incorrect addresses and fix registration or wait for heartbeat expiry
  3. Open/verify network path: firewall, security groups, k8s NetworkPolicy between client and server
  4. Increase transport connect timeout if RTT is high (e.g. seata.client.rm.connect-timeout-millis / tm equivalent)

Example fix

# application.yml
seata:
  client:
    tm:
      connect-timeout-millis: 10000   # was 3000, too low for the network
    rm:
      connect-timeout-millis: 10000
Defensive patterns

Strategy: retry

Validate before calling

// pre-connect reachability check (cheap, avoids exception path)
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 2000);
} catch (IOException ioe) {
    // server unreachable: fix network before letting seata connect
}

Try / catch

catch (FrameworkException e) {
    if (e.getMessage().contains("connect failed")) {
        Throwable cause = e.getCause(); // real reason: refused / timeout / no route
        // schedule retry with backoff; alert if persistent
    }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/27ae4613709794f9. Report an issue: GitHub.