{"record":{"id":"165954e6f1fbd052","repo":"apache/incubator-seata","slug":"can-not-connect-to-services-server","errorCode":null,"errorMessage":"can not connect to services-server.","messagePattern":"can not connect to services-server\\.","errorType":"exception","errorClass":"FrameworkException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientBootstrap.java","lineNumber":212,"sourceCode":"                    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) {\n                            addChannelPipelineLast(channel, channelHandlers);\n                        }\n                    }\n                });\n                channel = bootstrap.open().get();\n            }\n\n        } catch (Exception e) {\n            throw new FrameworkException(e, \"can not connect to services-server.\");\n        }\n\n        return channel;\n    }\n\n    /**\n     * Gets thread prefix.\n     *\n     * @param threadPrefix the thread prefix\n     * @return the thread prefix\n     */\n    private String getThreadPrefix(String threadPrefix) {\n        return threadPrefix + THREAD_PREFIX_SPLIT_CHAR + transactionRole.name();\n    }\n\n    private EventLoopGroup getOrCreateEventLoopGroupWorker(int selectorThreadSizeThreadSize) {\n        if (eventLoopGroupWorker == null) {\n            return createEventLoopGroupWorker(selectorThreadSizeThreadSize);","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/NettyClientBootstrap.java#L194-L230","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make sure client and server agree on the protocol setting (both grpc or both seata/TCP)","Read the cause in the stack trace: 'stream refused'/HTTP/2 errors point at protocol/LB issues, timeouts at network issues","Bypass or reconfigure HTTP/1-only intermediaries between client and server when using gRPC","If it happens during shutdown, ignore or delay client close until in-flight connects finish"],"exampleFix":"# before\nseata:\n  client:\n    protocol: grpc    # server is plain TCP\n\n# after (align both sides)\nseata:\n  client:\n    protocol: grpc    # and seata.server.protocol=grpc on the server","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (FrameworkException e) {\n    if (e.getMessage().contains(\"can not connect to services-server\")) {\n        Throwable c = e.getCause(); // grpc handshake / interruption detail\n        // fix protocol or LB config based on cause; retry with backoff\n    }\n}","preventionTips":["Keep protocol setting identical on client and server","Ensure LBs/middleboxes on the path support HTTP/2 when using gRPC","Avoid interrupting client threads during channel creation"],"tags":["grpc","protocol","connect","client"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}