alibaba/Sentinel · error · SentinelClusterException

REQUEST_TIME_OUT

REQUEST_TIME_OUT

Error message

request time out

What it means

NettyTransportClient.sendRequest() writes the request, registers a ChannelPromise keyed by xid in TokenClientPromiseHolder, and awaits it for ClusterClientConfigManager.getRequestTimeout() ms. If the promise is not completed within that window, it throws SentinelClusterException(REQUEST_TIME_OUT): the token server did not answer in time.

Source

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

    @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);
            if (entry == null || entry.getValue() == null) {
                // Should not go through here.
                throw new SentinelClusterException(ClusterErrorMessages.UNEXPECTED_STATUS);
            }
            return entry.getValue();
        } finally {
            TokenClientPromiseHolder.remove(xid);
        }
    }

    private int getCurrentId() {
        int pre, next;
        do {
            pre = idGenerator.get();
            next = pre >= MAX_ID ? MIN_ID : pre + 1;

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Increase requestTimeout in cluster client config (e.g. ClusterClientConfigManager.applyRequestTimeout or the requestTimeout property)
2. Check token server health, CPU/GC, and network RTT between client and server
3. Catch the timeout and fall back to local (standalone) flow rules so limiting still works
4. Scale or shard the token server if it is saturated

Example fix

// before
// default short timeout

// after
ClusterClientConfig config = new ClusterClientConfig()
    .setRequestTimeout(100); // ms, was too small
ClusterClientConfigManager.applyNewConfig(config);
try {
    TokenResult r = tokenService.requestToken(name, count, prioritized);
} catch (SentinelClusterException e) {
    // degrade to local mode
}

try {
    result = tokenService.requestToken(name, count, prioritized);
} catch (SentinelClusterException e) {
    if (ClusterErrorMessages.REQUEST_TIME_OUT.equals(e.getMessage())) {
        result = retryOnceOrFallback(name, count);
    } else {
        throw e;
    }
}

When it happens

Trigger: Token server slow/overloaded, GC pauses, or network latency exceeding the configured requestTimeout; requestTimeout left at a small default while the server is under heavy load; responses lost during connection churn so the promise never completes.

Common situations: Cluster token server under burst load; cross-datacenter latency; requestTimeout misconfigured (cluster-client requestTimeout property in ms); server restart while requests are in flight.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• CLIENT_NOT_READY
• 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/ee30612a0adbb03d. Report an issue: GitHub.