alibaba/nacos · error · NacosRuntimeException

SERVER_NOT_IMPLEMENTED

SERVER_NOT_IMPLEMENTED

Error message

Request Nacos server does not support %s feature.

What it means

Thrown by AiGrpcClient.checkServerAbilityOrThrow when the negotiated AbilityStatus for the required ability key is NOT_SUPPORTED. The gRPC connection is alive, but the connected Nacos server does not implement the requested AI feature (e.g. agent registry), so the operation is refused with SERVER_NOT_IMPLEMENTED (501-class). This protects the client from sending an unsupported request.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/remote/AiGrpcClient.java:776

     */
    public boolean isAbilitySupportedByServer(AbilityKey abilityKey) {
        return rpcClient.getConnectionAbility(abilityKey) == AbilityStatus.SUPPORTED;
    }
    
    private void checkServerAbilityOrThrow(AbilityKey abilityKey, String featureName) {
        if (!rpcClient.isRunning()) {
            throw new NacosRuntimeException(NacosException.SERVER_ERROR,
                String.format(
                    "Request Nacos server failed: connection is unavailable, unable to determine %s "
                        + "ability.",
                    featureName));
        }
        AbilityStatus abilityStatus = rpcClient.getConnectionAbility(abilityKey);
        if (AbilityStatus.SUPPORTED == abilityStatus) {
            return;
        }
        if (AbilityStatus.NOT_SUPPORTED == abilityStatus) {
            throw new NacosRuntimeException(NacosException.SERVER_NOT_IMPLEMENTED,
                String.format("Request Nacos server does not support %s feature.",
                    featureName));
        }
    }
    
    private void checkServerAbilityStrict(AbilityKey abilityKey, String featureName)
        throws NacosException {
        if (!rpcClient.isRunning()) {
            throw new NacosException(NacosException.SERVER_ERROR,
                "Request Nacos server failed: connection is unavailable, unable to determine "
                    + featureName + " ability.");
        }
        AbilityStatus abilityStatus = rpcClient.getConnectionAbility(abilityKey);
        if (AbilityStatus.SUPPORTED != abilityStatus) {
            throw new NacosException(NacosException.SERVER_NOT_IMPLEMENTED,
                "Request Nacos server does not support " + featureName + " feature.");
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Upgrade the Nacos server to a version that supports the AI registry feature.
2. Verify aiClient.isAbilitySupportedByServer(AbilityKey.SERVER_AGENT_REGISTRY) before calling AI APIs.
3. Fall back to a transport/API the server does support, or disable the AI feature in the client.

Example fix

// before
aiGrpcClient.subscribeAgentCard(agentName, version);
// after
if (!aiGrpcClient.isAbilitySupportedByServer(AbilityKey.SERVER_AGENT_REGISTRY)) {
    throw new IllegalStateException("Connected Nacos server lacks AI agent registry support; upgrade server");
}
aiGrpcClient.subscribeAgentCard(agentName, version);

if (!aiGrpcClient.isAbilitySupportedByServer(AbilityKey.SERVER_AGENT_REGISTRY)) {
    throw new IllegalStateException("Connected server does not support AI agent registry");
}
aiGrpcClient.subscribeAgentCard(agentName, version);

aiGrpcClient.isAbilitySupportedByServer(AbilityKey.SERVER_AGENT_REGISTRY)

try {
    aiGrpcClient.subscribeAgentCard(agentName, version);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED) {
        // server too old / feature disabled - upgrade or disable client feature
    }
    throw e;
}

When it happens

Trigger: Calling an AI registry operation against a Nacos server that predates the feature (older server version), or a server build with the AI module disabled, after the ability table reports NOT_SUPPORTED for SERVER_AGENT_REGISTRY.

Common situations: Client SDK version newer than the deployed server; server running an edition without AI registry support; feature flag disabled server-side; mixing a v3.2+ AI client against an older Nacos server.

Related errors

• SERVER_ERROR
• 501
• PARAMETER_MISSING
• MCP_SERVER_NOT_FOUND
• MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND

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