alibaba/nacos · error · NacosException

{exception.getErrCode()}

{exception.getErrCode()}

Error message

Failed to request API: {api} after all servers({servers}) tried: {exception.getMessage()}

What it means

Thrown by AiHttpClientProxy.reqApiStringWithHeader() after the retry loop exhausted every server. Used by queryAgentSpec() for AgentSpec JSON retrieval. Like reqApiBytesWithHeader, this variant short-circuits on 304 NOT_MODIFIED, so this error is only reached for non-304 failures on all servers. The last server's error code and message are propagated.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/remote/AiHttpClientProxy.java:795

            String server = servers.get(index % servers.size());
            try {
                return callServerStringWithHeader(api, params, server, resource);
            } catch (NacosException e) {
                if (NacosException.NOT_MODIFIED == e.getErrCode()) {
                    throw e;
                }
                exception = e;
                if (LOGGER.isDebugEnabled()) {
                    LOGGER.debug("Request {} to server {} failed.", api, server, e);
                }
            }
            index = (index + 1) % servers.size();
        }
        
        LOGGER.error("Request: {} failed, servers: {}, code: {}, msg: {}", api, servers,
            exception.getErrCode(),
            exception.getErrMsg());
        throw new NacosException(exception.getErrCode(),
            "Failed to request API: " + api + " after all servers(" + servers + ") tried: "
                + exception.getMessage());
    }
    
    private HttpRestResult<String> callServerStringWithHeader(String api,
        Map<String, String> params, String server, RequestResource resource)
        throws NacosException {
        Map<String, String> securityHeaders = securityProxy.getIdentityContext(resource);
        Header header = Header.newInstance();
        header.addAll(securityHeaders);
        
        String url = buildUrl(server, api);
        
        try {
            HttpRestResult<String> restResult = nacosRestTemplate.get(url, header,
                Query.newInstance().initParams(params), String.class);
            
            if (restResult.ok()) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Examine the inner exception code: 404 = not published, 500 = server error, 403 = auth issue.
2. Verify the AgentSpec name and namespace.
3. Check network connectivity and server health.
4. If 403, verify credentials and permissions.

Example fix

try {
    AgentSpecQueryResponse resp = aiService.queryAgentSpec("my-spec", version, label, md5);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.NOT_MODIFIED) {
        return; // cache still valid
    }
    log.error("queryAgentSpec failed on all servers: code={}, msg={}",
        e.getErrCode(), e.getErrMsg());
}

try {
    AgentSpecQueryResponse resp = aiService.queryAgentSpec(name, ver, label, cachedMd5);
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.NOT_MODIFIED) {
        return; // 304 propagated immediately
    }
    if (e.getErrCode() == NacosException.NOT_FOUND) {
        log.warn("AgentSpec '{}' not found", name);
        return;
    }
    log.error("queryAgentSpec failed: code={}, msg={}", e.getErrCode(), e.getErrMsg());
}

When it happens

Trigger: All servers returned a non-304 failure during queryAgentSpec(). Each callServerStringWithHeader() attempt threw a NacosException (not NOT_MODIFIED). The loop tried up to Math.max(servers.size(), 3) times.

Common situations: All server nodes down. AgentSpec not published (404 on all). Auth expired (403). Network partition. Server-side JSON serialization failure (500).

Related errors

• 400
• NOT_MODIFIED
• 304
• {restResult.getCode()}
• HTTP ${code} when fetching ${pageUrl}

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