{"record":{"id":"9f3a56bccc74f2a1","repo":"alibaba/nacos","slug":"20004-9f3a56","errorCode":"20004","errorMessage":"clientId [ {clientId} ] not exist","messagePattern":"clientId \\[ (.+?) \\] not exist","errorType":"http","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"naming/src/main/java/com/alibaba/nacos/naming/controllers/v3/ClientControllerV3.java","lineNumber":163,"sourceCode":"                clientServiceForm.getIp(),\n                clientServiceForm.getPort()));\n    }\n    \n    /**\n     * Query the responsible server for a given client based on its IP and port.\n     */\n    @Since(\"3.0.0\")\n    @GetMapping(\"/distro\")\n    @Secured(resource = UtilsAndCommons.CLIENT_CONTROLLER_V3_ADMIN_PATH, action = ActionTypes.READ,\n        apiType = ApiType.ADMIN_API)\n    public Result<Map<String, Object>> getResponsibleServer4Client(@RequestParam String ip,\n        @RequestParam String port) {\n        return Result.success(clientServiceV2Impl.getResponsibleServer4Client(ip, port));\n    }\n    \n    private void checkClientId(String clientId) throws NacosApiException {\n        if (!clientManager.contains(clientId)) {\n            throw new NacosApiException(HttpStatus.NOT_FOUND.value(), ErrorCode.RESOURCE_NOT_FOUND,\n                \"clientId [ \" + clientId + \" ] not exist\");\n        }\n    }\n}\n","sourceCodeStart":145,"sourceCodeEnd":168,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/controllers/v3/ClientControllerV3.java#L145-L168","documentation":"Thrown by ClientControllerV3.checkClientId when the requested client ID is not registered in the ClientManager. Returns HTTP 404 with ErrorCode.RESOURCE_NOT_FOUND=20004. This means the gRPC/HTTP connection-based client (identified by its clientId) is not known to this Nacos server node — it may have never connected, disconnected, or is managed by a different node.","triggerScenarios":"Calling an admin API endpoint on ClientControllerV3 that delegates to checkClientId (e.g. client detail, client publish info) with a clientId that clientManager.contains() returns false for. The clientId typically encodes ip:port or a connection-based identifier.","commonSituations":"Querying a client that has already disconnected (connection closed, client crashed). Querying a clientId that belongs to a different Nacos server node in the cluster (Distro ownership). Using a stale or fabricated clientId. The client connected to the cluster but this node does not hold its connection.","solutions":["Verify the clientId is currently connected by listing clients first (getClientList) and confirming the ID exists.","Route the query to the correct Nacos server node that owns the client connection (use the /distro endpoint to find the responsible server).","Re-register the client if it was unintentionally disconnected.","Check that the client is still alive and its heartbeat/connection is active."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// verify the client exists before querying detail\nList<String> clientIds = clientService.getClientList();\nif (!clientIds.contains(targetClientId)) {\n    // route to the responsible server via /distro or skip\n    log.warn(\"clientId {} not on this node\", targetClientId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ClientSummaryInfo detail = clientService.getClientDetail(clientId);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == NacosException.NOT_FOUND\n            || ErrorCode.RESOURCE_NOT_FOUND.getCode() == e.getErrCode()) {\n        // client disconnected or is on another node; refresh client list\n    } else { throw e; }\n}","preventionTips":["Always list clients first and confirm the target clientId exists on this node before detail queries.","Use the /distro endpoint to find which server owns a client before querying detail.","Treat client queries as potentially stale — clients can disconnect at any time."],"tags":["naming","client-management","not-found","admin-api","connection"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}