alibaba/Sentinel · error · SentinelClusterException

CLIENT_NOT_READY

CLIENT_NOT_READY

Error message

client not ready

What it means

NettyTransportClient.sendRequest() (cluster token client) first checks isReady(): the Netty channel must be non-null, the clientHandler set, and the handler started. If not, it throws SentinelClusterException with code/message CLIENT_NOT_READY. It means the client has not (yet) established its connection to the cluster token server, so no token request can be sent.

Source

Thrown at sentinel-cluster/sentinel-cluster-client-default/src/main/java/com/alibaba/csp/sentinel/cluster/client/NettyTransportClient.java:210

        cleanUp();
        failConnectedTime.set(0);

        RecordLog.info("[NettyTransportClient] Cluster transport client stopped");
    }

    private boolean validRequest(Request request) {
        return request != null && request.getType() >= 0;
    }

    @Override
    public boolean isReady() {
        return channel != null && clientHandler != null && clientHandler.hasStarted();
    }

    @Override
    public ClusterResponse sendRequest(ClusterRequest request) throws Exception {
        if (!isReady()) {
            throw new SentinelClusterException(ClusterErrorMessages.CLIENT_NOT_READY);
        }
        if (!validRequest(request)) {
            throw new SentinelClusterException(ClusterErrorMessages.BAD_REQUEST);
        }
        int xid = getCurrentId();
        try {
            request.setId(xid);

            channel.writeAndFlush(request);

            ChannelPromise promise = channel.newPromise();
            TokenClientPromiseHolder.putPromise(xid, promise);

            if (!promise.await(ClusterClientConfigManager.getRequestTimeout())) {
                throw new SentinelClusterException(ClusterErrorMessages.REQUEST_TIME_OUT);
            }

            SimpleEntry<ChannelPromise, ClusterResponse> entry = TokenClientPromiseHolder.getEntry(xid);

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Verify the token server address/port configuration (ClusterStateManager / cluster-client.properties) and that the server is reachable
2. Wait for client readiness or fail over to local/offline mode: catch SentinelClusterException and check the error type
3. Check logs for Netty connection failures (TokenClientHandler, connect timeouts)
4. If the race is at startup, delay or gate traffic until the client has started (check ClusterTransportClient.isReady())

Example fix

// before
TokenResult r = tokenService.requestToken(name, count, prioritized);

// after
TokenResult r;
try {
    r = tokenService.requestToken(name, count, prioritized);
} catch (SentinelClusterException e) {
    // fall back to local flow control while cluster client is not ready
    r = ClusterConstants.checkOkNoJoin ? TokenResult.ok() : localFallback(name, count);
}

ClusterTransportClient client = ClusterSpiManager.getClient(); // per version API
if (client == null || !client.isReady()) {
    // skip cluster request; use local mode
}

try {
    result = tokenService.requestToken(name, count, prioritized);
} catch (SentinelClusterException e) {
    if (ClusterErrorMessages.CLIENT_NOT_READY.equals(e.getMessage())) {
        result = localModeRequest(name, count); // degrade gracefully
    } else {
        throw e;
    }
}

When it happens

Trigger: Requesting flow tokens (cluster mode) before the Netty client connects to the token server; after the token server restarts or the connection drops and before reconnection; embedding the cluster client without calling start()/init properly (ClusterClientConfigManager state not bound to a live channel).

Common situations: Application startup race: requests arrive before the cluster client finishes connecting; token server down or address misconfigured (ClusterClientAssignAssigner / cluster-client config); network partitions causing silent channel loss; failover between embedded and token-server modes.

Related errors

• REQUEST_TIME_OUT
• BAD_REQUEST
• UNEXPECTED_STATUS
• Invalid request
• Invalid transport config in request

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/7c64fe6dee1de5b8. Report an issue: GitHub.