{"record":{"id":"b30c938a4aad1b1b","repo":"alibaba/nacos","slug":"20004-b30c93","errorCode":"20004","errorMessage":"no ips found for cluster {cluster} in service {service.getGroupedServiceName()}","messagePattern":"no ips found for cluster (.+?) in service (.+?)","errorType":"validation","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"naming/src/main/java/com/alibaba/nacos/naming/core/InstanceOperatorClientImpl.java","lineNumber":231,"sourceCode":"                healthOnly, true, null == subscriber ? StringUtils.EMPTY : subscriber.getIp());\n        // adapt for v1.x sdk\n        result.setName(NamingUtils.getGroupedName(result.getName(), result.getGroupName()));\n        return result;\n    }\n    \n    @Override\n    public Instance getInstance(String namespaceId, String groupName, String serviceName,\n        String cluster, String ip,\n        int port) throws NacosException {\n        Service service = Service.newService(namespaceId, groupName, serviceName, true);\n        return getInstance0(service, cluster, ip, port);\n    }\n    \n    private Instance getInstance0(Service service, String cluster, String ip, int port)\n        throws NacosException {\n        ServiceInfo serviceInfo = serviceStorage.getData(service);\n        if (serviceInfo.getHosts().isEmpty()) {\n            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,\n                \"no ips found for cluster \" + cluster + \" in service \"\n                    + service.getGroupedServiceName());\n        }\n        for (Instance each : serviceInfo.getHosts()) {\n            if (cluster.equals(each.getClusterName()) && ip.equals(each.getIp())\n                && port == each.getPort()) {\n                return each;\n            }\n        }\n        throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,\n            \"no matched ip found!\");\n    }\n    \n    @Override\n    public int handleBeat(String namespaceId, String groupName, String serviceName, String ip,\n        int port, String cluster,\n        RsInfo clientBeat, BeatInfoInstanceBuilder builder) throws NacosException {\n        Service service = Service.newService(namespaceId, groupName, serviceName, true);","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/core/InstanceOperatorClientImpl.java#L213-L249","documentation":"Thrown by InstanceOperatorClientImpl.getInstance0 when serviceStorage.getData(service) returns a ServiceInfo whose hosts list is empty. Error code NOT_FOUND=404 with ErrorCode.RESOURCE_NOT_FOUND=20004. The service may exist but has no registered healthy instances for the requested cluster, so the specific ip:port:cluster lookup cannot succeed.","triggerScenarios":"Calling getInstance(namespaceId, groupName, serviceName, cluster, ip, port) where the service exists in storage but has zero instances (all deregistered or all unhealthy). The hosts list is empty, so the guard fires before the per-instance ip/port matching loop.","commonSituations":"All instances for the service have deregistered or failed health checks. Instances exist but none match the requested cluster. Querying immediately after service creation before any instance registered. Instances are marked unhealthy and filtered out. Temporary empty state during service migration.","solutions":["Register at least one healthy instance under the requested service and cluster.","Verify the cluster name matches an existing instance's cluster.","Check instance health status — unhealthy instances may be excluded from the hosts list.","If this is transient, retry after instances have registered and passed health checks."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"ServiceInfo info = serviceStorage.getData(service);\nif (info.getHosts() == null || info.getHosts().isEmpty()) {\n    // no instances available; register one or return not-found gracefully\n    log.warn(\"no instances for service {} cluster {}\", service.getGroupedServiceName(), cluster);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Instance inst = instanceOperator.getInstance(namespaceId, groupName, serviceName, cluster, ip, port);\n} catch (NacosApiException e) {\n    if (ErrorCode.RESOURCE_NOT_FOUND.getCode() == e.getErrCode()\n            || e.getErrCode() == NacosException.NOT_FOUND) {\n        // no instances found; register one or wait for health checks to pass\n    } else { throw e; }\n}","preventionTips":["Ensure at least one healthy instance is registered under the target service and cluster before querying.","Check instance health status — unhealthy instances may not appear in the hosts list.","Retry after a brief delay if querying immediately after instance registration."],"tags":["naming","instance","not-found","health-check","admin-api"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}