alibaba/nacos · critical · NacosRuntimeException

SERVER_ERROR

SERVER_ERROR

Error message

Request Nacos server failed: connection is unavailable, unable to determine %s ability.

What it means

Thrown by AiGrpcClient.checkServerAbilityOrThrow when rpcClient.isRunning() is false. Before dispatching an AI gRPC operation the client must confirm the server actually supports the feature via ability negotiation, which is impossible without a live connection. SERVER_ERROR (500-class) indicates a server-side/connection state failure rather than a client argument error.

Source

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

    }
    
    public boolean isEnable() {
        return rpcClient.isRunning();
    }
    
    /**
     * Determine whether nacos-server supports the capability.
     *
     * @param abilityKey ability key
     * @return true if supported, otherwise false
     */
    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 {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Confirm the Nacos server endpoints are reachable and the client has fully started before issuing AI calls.
2. Check aiClient.isEnable() / isAbilitySupportedByServer before calling AI registry methods.
3. Wait for client readiness (connection established) or retry after a backoff for startup races.
4. Ensure shutdown is not called on a client instance that is still being used.

Example fix

// before
aiGrpcClient.subscribeAgentCard(agentName, version);
// after
if (!aiGrpcClient.isEnable()) {
    throw new IllegalStateException("AI client not connected; ensure server is reachable");
}
aiGrpcClient.subscribeAgentCard(agentName, version);

if (!aiGrpcClient.isEnable()) {
    throw new IllegalStateException("AI client connection not running");
}
aiGrpcClient.subscribeAgentCard(agentName, version);

aiGrpcClient.isEnable() // true only when rpcClient.isRunning()

try {
    aiGrpcClient.subscribeAgentCard(agentName, version);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR
        && e.getMessage().contains("connection is unavailable")) {
        // connection/startup race - wait for readiness and retry
    }
    throw e;
}

When it happens

Trigger: Any AI registry operation (subscribe/unsubscribe agent card, etc.) that routes through checkServerAbilityOrThrow while the gRPC rpcClient is not started, has been shut down, or the connection has not yet been established/negotiated.

Common situations: Calling AI APIs before the client finished connecting; client was shut down but reused; network partition or all server endpoints unreachable so the rpcClient never transitioned to running; server started but ability table not yet exchanged.

Related errors

• SERVER_NOT_IMPLEMENTED
• 500
• DATA_ACCESS_ERROR
• RESOURCE_NOT_FOUND
• PARAMETER_MISSING

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