apache/incubator-seata · error · FrameworkException

connect cancelled, can not connect to services-server.

Error message

connect cancelled, can not connect to services-server.

What it means

FrameworkException from NettyClientBootstrap.getNewChannel when the Netty connect future reports isCancelled() after awaiting the connect timeout. A cancelled connect future is rare — it usually indicates the future was cancelled externally or the channel setup aborted — and is reported with cause f.cause() if present.

Source

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

            eventLoopGroupWorker.shutdownGracefully();
        } catch (Exception exx) {
            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());

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Ensure the client is not being shut down while reconnection is in progress (stop transactions before closing the seata client)
  2. Increase transport.connect-timeout-millis so connects are not abandoned prematurely
  3. Verify event loop threads are healthy (no ThreadDeath/OOM in logs around the same time)
  4. Retry the operation: cancelled connects are transient by nature — the next reconnect cycle typically succeeds
Defensive patterns

Strategy: retry

Try / catch

catch (FrameworkException e) {
    if (e.getMessage().contains("connect cancelled")) {
        // transient: retry once after a short delay; if persistent, check shutdown state
    }
}

Prevention

When it happens

Trigger: bootstrap.connect(address).await(connectTimeoutMillis) completing in a cancelled state: the connect attempt was cancelled before it succeeded or failed, e.g. by shutdown of the client event loop or an internal cancellation during channel creation.

Common situations: Client shutting down concurrently with a reconnect attempt; event loop group closed while a pooled channel was being created; very low connect timeouts causing the operation to be abandoned.

Related errors

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