alibaba/nacos · critical · NacosException

502

502

Error message

No available server after {} retries, last tried server: {}

What it means

Thrown by ClientHttpProxy when all server retry attempts are exhausted AND no request exception was ever captured (requestException == null). This means the client could not even establish a working request to any server. Error code is BAD_GATEWAY=502. This is the harder failure — no server responded with a processable result at all.

Source

Thrown at maintainer-client/src/main/java/com/alibaba/nacos/maintainer/client/remote/ClientHttpProxy.java:170

            if (isFail(resultCode)) {
                currentServerAddr = serverListManager.genNextServer();
            }
            retryCount--;
            
            try {
                Thread.sleep(100);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
        
        if (null != requestException) {
            throw new NacosException(requestException.getErrCode(),
                "No available server after " + maxRetry + " retries, last tried server: "
                    + currentServerAddr
                    + ", last errMsg: " + requestException.getErrMsg());
        }
        throw new NacosException(NacosException.BAD_GATEWAY,
            "No available server after " + maxRetry + " retries, last tried server: "
                + currentServerAddr);
    }
    
    private String resolveErrorMessage(HttpRestResult<String> result) {
        String responseBody = result.getData();
        if (StringUtils.isNotBlank(responseBody)) {
            try {
                Result<Object> response =
                    JsonUtils.toObj(responseBody, new NacosTypeReference<Result<Object>>() {
                    });
                if (response != null) {
                    String message = response.getMessage();
                    Object data = response.getData();
                    if (data instanceof String && StringUtils.isNotBlank((String) data)) {
                        if (StringUtils.isNotBlank(message) && !data.equals(message)) {
                            return message + ": " + data;
                        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Verify the server address property (serverAddr) is correct and the port is open: telnet or nc to the Nacos server.
Check that at least one Nacos server node is running and healthy.
Confirm no firewall, security group, or network policy blocks the connection.
Ensure the server list manager has been initialized with valid addresses before making API calls.

Defensive patterns

Strategy: retry

Validate before calling

// verify connectivity before relying on the client
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(host, port), 2000);
} catch (IOException e) {
    throw new IllegalStateException("Nacos server unreachable: " + host + ":" + port, e);
}

Try / catch

try {
    result = maintainerService.someApiCall(...);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.BAD_GATEWAY) {
        // no server was reachable at all — check network/server health
        log.error("All Nacos servers unreachable: {}", e.getMessage());
        // optionally retry with backoff after confirming network
    }
}

Prevention

Validate server addresses and port reachability at application startup.
Configure multiple server addresses for failover redundancy.
Set up health checks and alerts on Nacos server availability.
Ensure the server list manager is populated before issuing API calls.

When it happens

Trigger: The HTTP proxy retry loop completes all iterations without ever capturing a requestException — typically because every server address was unreachable (connection refused, DNS failure, timeout) or the server list itself was empty/exhausted without an exception being stored.

Common situations: Wrong server address in properties (typo, wrong port). Firewall or network ACL blocking the Nacos server port. DNS resolution failure for the server hostname. All Nacos server nodes are down. Server list manager has not yet been populated with addresses.

Related errors

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