alibaba/nacos · error · NacosApiException

20004

20004

Error message

no ips found for cluster {cluster} in service {service.getGroupedServiceName()}

What it means

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.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/core/InstanceOperatorClientImpl.java:231

                healthOnly, true, null == subscriber ? StringUtils.EMPTY : subscriber.getIp());
        // adapt for v1.x sdk
        result.setName(NamingUtils.getGroupedName(result.getName(), result.getGroupName()));
        return result;
    }
    
    @Override
    public Instance getInstance(String namespaceId, String groupName, String serviceName,
        String cluster, String ip,
        int port) throws NacosException {
        Service service = Service.newService(namespaceId, groupName, serviceName, true);
        return getInstance0(service, cluster, ip, port);
    }
    
    private Instance getInstance0(Service service, String cluster, String ip, int port)
        throws NacosException {
        ServiceInfo serviceInfo = serviceStorage.getData(service);
        if (serviceInfo.getHosts().isEmpty()) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
                "no ips found for cluster " + cluster + " in service "
                    + service.getGroupedServiceName());
        }
        for (Instance each : serviceInfo.getHosts()) {
            if (cluster.equals(each.getClusterName()) && ip.equals(each.getIp())
                && port == each.getPort()) {
                return each;
            }
        }
        throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
            "no matched ip found!");
    }
    
    @Override
    public int handleBeat(String namespaceId, String groupName, String serviceName, String ip,
        int port, String cluster,
        RsInfo clientBeat, BeatInfoInstanceBuilder builder) throws NacosException {
        Service service = Service.newService(namespaceId, groupName, serviceName, true);

View on GitHub (pinned to 9b989acdf1)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

ServiceInfo info = serviceStorage.getData(service);
if (info.getHosts() == null || info.getHosts().isEmpty()) {
    // no instances available; register one or return not-found gracefully
    log.warn("no instances for service {} cluster {}", service.getGroupedServiceName(), cluster);
}

Try / catch

try {
    Instance inst = instanceOperator.getInstance(namespaceId, groupName, serviceName, cluster, ip, port);
} catch (NacosApiException e) {
    if (ErrorCode.RESOURCE_NOT_FOUND.getCode() == e.getErrCode()
            || e.getErrCode() == NacosException.NOT_FOUND) {
        // no instances found; register one or wait for health checks to pass
    } else { throw e; }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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