apache/incubator-seata · error · FrameworkException

can not connect to services-server.

Error message

can not connect to services-server.

What it means

Catch-all FrameworkException from NettyClientBootstrap.getNewChannel: any exception escaping the channel-creation block that is not the explicit cancelled/failed branches — most commonly the gRPC path, where bootstrap.open().get() (opening the HTTP/2 stream channel) throws, or interruption while awaiting. The original exception is wrapped as the cause.

Solutions

  1. Make sure client and server agree on the protocol setting (both grpc or both seata/TCP)
  2. Read the cause in the stack trace: 'stream refused'/HTTP/2 errors point at protocol/LB issues, timeouts at network issues
  3. Bypass or reconfigure HTTP/1-only intermediaries between client and server when using gRPC
  4. If it happens during shutdown, ignore or delay client close until in-flight connects finish

Example fix

# before
seata:
  client:
    protocol: grpc    # server is plain TCP

# after (align both sides)
seata:
  client:
    protocol: grpc    # and seata.server.protocol=grpc on the server
Defensive patterns

Strategy: try-catch

Try / catch

catch (FrameworkException e) {
    if (e.getMessage().contains("can not connect to services-server")) {
        Throwable c = e.getCause(); // grpc handshake / interruption detail
        // fix protocol or LB config based on cause; retry with backoff
    }
}

Prevention

When it happens

Trigger: Using seata with protocol=GRPC: the TCP connect succeeds but Http2StreamChannelBootstrap.open() fails (HTTP/2 handshake rejected, stream refused, TLS mismatch); or an InterruptedException during the await.

Common situations: Server not actually speaking gRPC on that port (protocol mismatch: client grpc, server seata/tcp or vice versa); HTTP/2-incompatible middleboxes/LBs (some only do HTTP/1); TLS config differences on the gRPC path; thread interruption during client shutdown.

Related errors

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

Appendix: source

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

                    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) {
                            addChannelPipelineLast(channel, channelHandlers);
                        }
                    }
                });
                channel = bootstrap.open().get();
            }

        } catch (Exception e) {
            throw new FrameworkException(e, "can not connect to services-server.");
        }

        return channel;
    }

    /**
     * Gets thread prefix.
     *
     * @param threadPrefix the thread prefix
     * @return the thread prefix
     */
    private String getThreadPrefix(String threadPrefix) {
        return threadPrefix + THREAD_PREFIX_SPLIT_CHAR + transactionRole.name();
    }

    private EventLoopGroup getOrCreateEventLoopGroupWorker(int selectorThreadSizeThreadSize) {
        if (eventLoopGroupWorker == null) {
            return createEventLoopGroupWorker(selectorThreadSizeThreadSize);

View on GitHub (pinned to e01f97c6db)