{"record":{"id":"91e5d866fdc4ffd6","repo":"alibaba/nacos","slug":"server-error-91e5d8","errorCode":"SERVER_ERROR","errorMessage":"Request Nacos server failed: connection is unavailable, unable to determine %s ability.","messagePattern":"Request Nacos server failed: connection is unavailable, unable to determine (.+?) ability\\.","errorType":"exception","errorClass":"NacosRuntimeException","httpStatus":null,"severity":"critical","filePath":"client/src/main/java/com/alibaba/nacos/client/ai/remote/AiGrpcClient.java","lineNumber":765,"sourceCode":"    }\n    \n    public boolean isEnable() {\n        return rpcClient.isRunning();\n    }\n    \n    /**\n     * Determine whether nacos-server supports the capability.\n     *\n     * @param abilityKey ability key\n     * @return true if supported, otherwise false\n     */\n    public boolean isAbilitySupportedByServer(AbilityKey abilityKey) {\n        return rpcClient.getConnectionAbility(abilityKey) == AbilityStatus.SUPPORTED;\n    }\n    \n    private void checkServerAbilityOrThrow(AbilityKey abilityKey, String featureName) {\n        if (!rpcClient.isRunning()) {\n            throw new NacosRuntimeException(NacosException.SERVER_ERROR,\n                String.format(\n                    \"Request Nacos server failed: connection is unavailable, unable to determine %s \"\n                        + \"ability.\",\n                    featureName));\n        }\n        AbilityStatus abilityStatus = rpcClient.getConnectionAbility(abilityKey);\n        if (AbilityStatus.SUPPORTED == abilityStatus) {\n            return;\n        }\n        if (AbilityStatus.NOT_SUPPORTED == abilityStatus) {\n            throw new NacosRuntimeException(NacosException.SERVER_NOT_IMPLEMENTED,\n                String.format(\"Request Nacos server does not support %s feature.\",\n                    featureName));\n        }\n    }\n    \n    private void checkServerAbilityStrict(AbilityKey abilityKey, String featureName)\n        throws NacosException {","sourceCodeStart":747,"sourceCodeEnd":783,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/ai/remote/AiGrpcClient.java#L747-L783","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the Nacos server endpoints are reachable and the client has fully started before issuing AI calls.","Check aiClient.isEnable() / isAbilitySupportedByServer before calling AI registry methods.","Wait for client readiness (connection established) or retry after a backoff for startup races.","Ensure shutdown is not called on a client instance that is still being used."],"exampleFix":"// before\naiGrpcClient.subscribeAgentCard(agentName, version);\n// after\nif (!aiGrpcClient.isEnable()) {\n    throw new IllegalStateException(\"AI client not connected; ensure server is reachable\");\n}\naiGrpcClient.subscribeAgentCard(agentName, version);","handlingStrategy":"try-catch","validationCode":"if (!aiGrpcClient.isEnable()) {\n    throw new IllegalStateException(\"AI client connection not running\");\n}\naiGrpcClient.subscribeAgentCard(agentName, version);","typeGuard":"aiGrpcClient.isEnable() // true only when rpcClient.isRunning()","tryCatchPattern":"try {\n    aiGrpcClient.subscribeAgentCard(agentName, version);\n} catch (NacosRuntimeException e) {\n    if (e.getErrCode() == NacosException.SERVER_ERROR\n        && e.getMessage().contains(\"connection is unavailable\")) {\n        // connection/startup race - wait for readiness and retry\n    }\n    throw e;\n}","preventionTips":["Check isEnable()/isAbilitySupportedByServer before AI operations.","Ensure the client is fully started before first use.","Do not reuse a client after shutdown.","Verify server reachability and credentials at startup."],"tags":["ai","grpc","connection","ability-negotiation","server-error"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}