{"record":{"id":"ee30612a0adbb03d","repo":"alibaba/Sentinel","slug":"request-time-out","errorCode":"REQUEST_TIME_OUT","errorMessage":"request time out","messagePattern":"request time out","errorType":"exception","errorClass":"SentinelClusterException","httpStatus":null,"severity":"error","filePath":"sentinel-cluster/sentinel-cluster-client-default/src/main/java/com/alibaba/csp/sentinel/cluster/client/NettyTransportClient.java","lineNumber":225,"sourceCode":"    @Override\n    public ClusterResponse sendRequest(ClusterRequest request) throws Exception {\n        if (!isReady()) {\n            throw new SentinelClusterException(ClusterErrorMessages.CLIENT_NOT_READY);\n        }\n        if (!validRequest(request)) {\n            throw new SentinelClusterException(ClusterErrorMessages.BAD_REQUEST);\n        }\n        int xid = getCurrentId();\n        try {\n            request.setId(xid);\n\n            channel.writeAndFlush(request);\n\n            ChannelPromise promise = channel.newPromise();\n            TokenClientPromiseHolder.putPromise(xid, promise);\n\n            if (!promise.await(ClusterClientConfigManager.getRequestTimeout())) {\n                throw new SentinelClusterException(ClusterErrorMessages.REQUEST_TIME_OUT);\n            }\n\n            SimpleEntry<ChannelPromise, ClusterResponse> entry = TokenClientPromiseHolder.getEntry(xid);\n            if (entry == null || entry.getValue() == null) {\n                // Should not go through here.\n                throw new SentinelClusterException(ClusterErrorMessages.UNEXPECTED_STATUS);\n            }\n            return entry.getValue();\n        } finally {\n            TokenClientPromiseHolder.remove(xid);\n        }\n    }\n\n    private int getCurrentId() {\n        int pre, next;\n        do {\n            pre = idGenerator.get();\n            next = pre >= MAX_ID ? MIN_ID : pre + 1;","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/alibaba/Sentinel/blob/a3f40ba8e900c8489bd520274739f17235a7721c/sentinel-cluster/sentinel-cluster-client-default/src/main/java/com/alibaba/csp/sentinel/cluster/client/NettyTransportClient.java#L207-L243","documentation":"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.","triggerScenarios":"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.","commonSituations":"Cluster token server under burst load; cross-datacenter latency; requestTimeout misconfigured (cluster-client requestTimeout property in ms); server restart while requests are in flight.","solutions":["Increase requestTimeout in cluster client config (e.g. ClusterClientConfigManager.applyRequestTimeout or the requestTimeout property)","Check token server health, CPU/GC, and network RTT between client and server","Catch the timeout and fall back to local (standalone) flow rules so limiting still works","Scale or shard the token server if it is saturated"],"exampleFix":"// before\n// default short timeout\n\n// after\nClusterClientConfig config = new ClusterClientConfig()\n    .setRequestTimeout(100); // ms, was too small\nClusterClientConfigManager.applyNewConfig(config);\ntry {\n    TokenResult r = tokenService.requestToken(name, count, prioritized);\n} catch (SentinelClusterException e) {\n    // degrade to local mode\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    result = tokenService.requestToken(name, count, prioritized);\n} catch (SentinelClusterException e) {\n    if (ClusterErrorMessages.REQUEST_TIME_OUT.equals(e.getMessage())) {\n        result = retryOnceOrFallback(name, count);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Size requestTimeout generously relative to network RTT and server load","Load-test the token server and scale it before production traffic peaks","Implement local-mode fallback so timeouts do not disable rate limiting entirely"],"tags":["cluster","timeout","netty","network","token-server"],"backgroundTag":null,"analyzedSha":"a3f40ba8e900c8489bd520274739f17235a7721c","analyzedAt":"2026-08-14T11:10:30.678Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}