alibaba/nacos · error · TimeoutException

request timeout after {timeout} milliseconds, requestId={req

Error message

request timeout after {timeout} milliseconds, requestId={requestId}, connectionId={connectionId}

What it means

DefaultRequestFuture.get throws a TimeoutException when the server has not produced a response within the configured timeout. The message includes timeout (ms), requestId, and connectionId to aid diagnosis. It indicates the request was sent but no reply arrived in time.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/remote/DefaultRequestFuture.java:169

            }
        } else if (timeout > 0) {
            long end = System.currentTimeMillis() + timeout;
            long waitTime = timeout;
            synchronized (this) {
                while (!isDone && waitTime > 0) {
                    wait(waitTime);
                    waitTime = end - System.currentTimeMillis();
                }
            }
        }
        
        if (isDone) {
            return response;
        } else {
            if (timeoutFuture == null && futureTrigger != null) {
                futureTrigger.triggerOnTimeout();
            }
            throw new TimeoutException(
                "request timeout after " + timeout + " milliseconds, requestId=" + requestId
                    + ", connectionId="
                    + connectionId);
        }
    }
    
    class CallBackHandler implements Runnable {
        
        @Override
        public void run() {
            if (exception != null) {
                requestCallBack.onException(exception);
            } else {
                requestCallBack.onResponse(response);
            }
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Check server health, GC logs, and network latency between client and server.
Increase the client request timeout property for large-payload or slow operations.
Verify the gRPC connection is still alive; let the SDK reconnect.
Retry with exponential backoff; idempotent reads are safe to retry.
Reduce payload size or shard batch operations.

Example fix

// before
Properties p = new Properties();
p.setProperty("serverAddr", "nacos:8848");
NamingService ns = NacosFactory.createNamingService(p);  // default timeout

// after
Properties p = new Properties();
p.setProperty("serverAddr", "nacos:8848");
p.setProperty("com.alibaba.nacos.naming.request.timeout.ms", "10000");
NamingService ns = NacosFactory.createNamingService(p);

Defensive patterns

Strategy: retry

Try / catch

int attempt = 0;
while (true) {
    try {
        return future.get(timeoutMs);
    } catch (TimeoutException e) {
        if (++attempt > MAX_RETRIES) throw e;
        sleep(backoffMillis(attempt));  // exponential backoff
    }
}

Prevention

Size the client timeout to expected server latency plus headroom.
Monitor gRPC connection health and reconnect proactively.
Make read operations idempotent so retries are safe.
Watch server GC and load metrics; timeouts often originate server-side.

When it happens

Trigger: Any gRPC request to the Nacos server (config get/publish, instance register, subscribe) that does not receive a response within the client timeout window.

Common situations: Server GC pause or overload; network partition; gRPC connection silently dropped; request queue saturated on server; timeout set too low for a large payload (e.g. big config publish).

Understand the failure class

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

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/6262550f508d62c1. Report an issue: GitHub.