alibaba/nacos · error · NacosException

{restResult.getCode()}

{restResult.getCode()}

Error message

{restResult.getMessage()}

What it means

Thrown by callServerBytes() when the server returns a non-OK, non-304, non-403 HTTP status code. The HTTP status code becomes the NacosException error code, and the server's response message becomes the error message. This is a catch-all for unexpected HTTP responses during byte[] API calls (e.g., 404 Not Found, 500 Internal Server Error, 502 Bad Gateway).

Source

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

        Header header = Header.newInstance();
        header.addAll(securityHeaders);
        
        String url = buildUrl(server, api);
        
        try {
            HttpRestResult<byte[]> restResult = nacosRestTemplate.get(url, header,
                Query.newInstance().initParams(params), byte[].class);
            
            if (restResult.ok()) {
                return restResult.getData();
            }
            if (HttpURLConnection.HTTP_NOT_MODIFIED == restResult.getCode()) {
                throw new NacosException(NacosException.NOT_MODIFIED, "not modified");
            }
            if (HttpURLConnection.HTTP_FORBIDDEN == restResult.getCode()) {
                securityProxy.reLogin();
            }
            throw new NacosException(restResult.getCode(), restResult.getMessage());
        } catch (NacosException e) {
            throw e;
        } catch (Exception e) {
            LOGGER.error("[AI-HTTP] Failed to request {}", url, e);
            throw new NacosException(NacosException.SERVER_ERROR, e);
        }
    }
    
    /**
     * Variant of {@link #callServerBytes} that exposes the raw {@link HttpRestResult} so callers
     * can inspect response headers (e.g. {@code X-Nacos-Skill-Md5}). Status code translation rules
     * mirror {@link #callServerBytes}: 304 raises {@link NacosException#NOT_MODIFIED}, 403
     * triggers a security re-login before bubbling the original status code up.
     */
    private HttpRestResult<byte[]> callServerBytesWithHeader(String api,
        Map<String, String> params, String server, RequestResource resource)
        throws NacosException {
        Map<String, String> securityHeaders = securityProxy.getIdentityContext(resource);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Check getErrCode() to determine the HTTP status: 404 = resource not found, 500 = server error, 503 = overloaded.
2. For 404: verify the resource name, version, and namespace are correct and that the resource has been published.
3. For 500/502/503: check Nacos server logs for stack traces, verify server health.
4. For 400: validate request parameters (skillName, version, label).

Example fix

try {
    byte[] zip = aiService.downloadSkill("my-skill", "1.0", null);
} catch (NacosException e) {
    switch (e.getErrCode()) {
        case NacosException.NOT_FOUND:
            log.warn("Skill 'my-skill' not found on server");
            break;
        case NacosException.SERVER_ERROR:
            log.error("Server error downloading skill: {}", e.getErrMsg());
            break;
        default:
            log.error("HTTP {} downloading skill: {}", e.getErrCode(), e.getErrMsg());
    }
}

try {
    byte[] zip = aiService.downloadSkill(name, ver, label);
} catch (NacosException e) {
    switch (e.getErrCode()) {
        case NacosException.NOT_FOUND:
            log.warn("Skill not found: {}", name);
            break;
        case NacosException.SERVER_ERROR:
            log.error("Server error: {}", e.getErrMsg());
            break;
        case NacosException.NO_RIGHT:
            log.error("Access denied");
            break;
        default:
            log.error("HTTP {}: {}", e.getErrCode(), e.getErrMsg());
    }
}

When it happens

Trigger: The nacosRestTemplate.get() call succeeded at the HTTP transport level but returned a status code outside the handled set (200, 304, 403). The skill artifact or resource does not exist (404), the server hit an internal error (500), or a gateway/proxy returned an error (502, 503).

Common situations: 404: skill/agentSpec name does not exist or has not been published. 500: server-side exception (storage failure, NPE). 502/503: reverse proxy or load balancer in front of Nacos is misconfigured or the backend is down. 400: malformed request parameters.

Related errors

• 304
• NOT_MODIFIED
• 400
• {exception.getErrCode()}
• Can't get single data from batched data.

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