alibaba/nacos · error · NacosException

{result.getCode()}

{result.getCode()}

Error message

{remoteResultMessage}

What it means

Thrown by RemoteServerUtil.singleCheckResult() when an HTTP result from a remote Nacos server call does not pass result.ok() — meaning the server returned a non-success code. This is the central error-propagation method used by all remote service operations (user management, visibility grants). It wraps the remote code and message into a NacosException that callers then catch and re-throw. The code is dynamic (result.getCode()) so it carries whatever the remote server reported.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/utils/RemoteServerUtil.java:117

        int actual = index.getAndUpdate(operand -> (operand + 1) % serverAddresses.size());
        return serverAddresses.get(actual);
    }
    
    public static String getRemoteServerContextPath() {
        return remoteServerContextPath;
    }
    
    /**
     * Single check http result, if not success, wrapper result as Nacos exception.
     *
     * @param result http execute result
     * @throws NacosException wrapper result as NacosException
     */
    public static void singleCheckResult(HttpRestResult<String> result) throws NacosException {
        if (result.ok()) {
            return;
        }
        throw new NacosException(result.getCode(), result.getMessage());
    }
    
    /**
     * Build the remote server identity header from the server module configuration.
     *
     * @return remote server identity header
     */
    public static Header buildServerRemoteHeader() {
        Header header = Header.newInstance();
        NacosAuthConfig config = NacosAuthConfigHolder.getInstance()
            .getNacosAuthConfigByScope(ApiType.OPEN_API.name());
        if (config != null && StringUtils.isNotBlank(config.getServerIdentityKey())) {
            header.addParam(config.getServerIdentityKey(), config.getServerIdentityValue());
        }
        return header;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect the NacosException errCode — it carries the remote server's original Result code which identifies the specific failure.
2. For auth errors (403), verify the access token and server identity headers are correctly forwarded.
3. For server errors (500), check the remote server's logs for the root cause.
4. For not-found errors (404), verify the resource exists on the remote server before retrying.

Example fix

// Handle the propagated remote error at the call site:
try {
    RemoteServerUtil.singleCheckResult(result);
} catch (NacosException e) {
    // e.getErrCode() carries the remote server's Result code
    // e.getErrMsg() carries the remote server's error message
    log.warn("Remote operation failed: code={}, msg={}", e.getErrCode(), e.getErrMsg());
    throw e;
}

try {
    RemoteServerUtil.singleCheckResult(result);
} catch (NacosException e) {
    // e.getErrCode() = remote Result code, e.getErrMsg() = remote error message
    log.warn("Remote call failed: code={}, msg={}", e.getErrCode(), e.getErrMsg());
    throw e;
}

When it happens

Trigger: Any remote HTTP call (createUser, deleteUser, listUsers, grant, revoke, etc.) where the remote Nacos server returns a non-OK Result — e.g. code 403 (access denied), code 404 (not found), code 500 (server error), or any other non-zero Result code.

Common situations: The forwarded access token is expired or invalid; the calling user lacks the required permissions on the remote server; the remote server has an internal error; the requested resource doesn't exist; the server identity verification fails.

Related errors

• SERVER_ERROR
• Request parameter `agentSpecCard` should not be null or empt
• Request parameter `agentSpecCard` is invalid and cannot be p
• Required parameter `agentSpecCard.name` is not present.
• Request parameter `name` should not be null or empty.

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