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.

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)

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.