alibaba/nacos · error · NacosApiException

21004

21004

Error message

service not found, namespace: {namespaceId}, service: {service}

What it means

Thrown by InstanceOperatorClientImpl.updateInstance when the target service does not exist in the ServiceManager singleton registry. Uses INVALID_PARAM=400 (HTTP) with ErrorCode.INSTANCE_ERROR=21004. The service must already be registered before an instance can be updated. Note the message includes namespaceId and the Service object (which includes the grouped name).

Source

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

        String clientId = IpPortBasedClient.getClientId(instance.toInetAddr(), ephemeral);
        if (!clientManager.contains(clientId)) {
            Loggers.SRV_LOG.warn("remove instance from non-exist client: {}", clientId);
            return;
        }
        Service service = Service.newService(namespaceId, groupName, serviceName, ephemeral);
        clientOperationService.deregisterInstance(service, instance, clientId);
    }
    
    @Override
    public void updateInstance(String namespaceId, String groupName, String serviceName,
        Instance instance)
        throws NacosException {
        NamingUtils.checkInstanceIsLegal(instance);
        
        Service service =
            Service.newService(namespaceId, groupName, serviceName, instance.isEphemeral());
        if (!ServiceManager.getInstance().containSingleton(service)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.INSTANCE_ERROR,
                "service not found, namespace: " + namespaceId + ", service: " + service);
        }
        String metadataId = InstancePublishInfo.genMetadataId(instance.getIp(), instance.getPort(),
            instance.getClusterName());
        metadataOperateService.updateInstanceMetadata(service, metadataId, buildMetadata(instance));
        NotifyCenter.publishEvent(new InfoChangeEvent.InstanceInfoChangeEvent(service, instance));
    }
    
    private InstanceMetadata buildMetadata(Instance instance) {
        InstanceMetadata result = new InstanceMetadata();
        result.setEnabled(instance.isEnabled());
        result.setWeight(instance.getWeight());
        result.getExtendData().putAll(filterNullValue(instance.getMetadata()));
        return result;
    }
    
    private Map<String, String> filterNullValue(Map<String, String> metadata) {
        return metadata.entrySet().stream().filter(entry -> entry.getValue() != null)

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Register the service and at least one instance first, then use updateInstance.
2. Verify the service exists with the matching ephemeral flag (the Service is created with instance.isEphemeral()).
3. Check namespaceId, groupName, and serviceName for correctness.
4. If the service was deleted, re-register it before updating instances.

Service svc = Service.newService(namespaceId, groupName, serviceName, instance.isEphemeral());
if (!ServiceManager.getInstance().containSingleton(svc)) {
    throw new IllegalStateException(
        "Cannot update instance: service " + groupName + "/" + serviceName
        + " (ephemeral=" + instance.isEphemeral() + ") not found");
}

try {
    instanceOperator.updateInstance(namespaceId, groupName, serviceName, instance);
} catch (NacosApiException e) {
    if (ErrorCode.INSTANCE_ERROR.getCode() == e.getErrCode()
            && e.getMessage().contains("service not found")) {
        // register the service/instance first, then retry the update
    } else { throw e; }
}

When it happens

Trigger: Calling updateInstance(namespaceId, groupName, serviceName, instance) for a service where ServiceManager.containSingleton returns false. The instance update path requires the service to pre-exist because it writes instance metadata keyed by the service.

Common situations: Updating an instance for a service that was never registered (instances are typically registered, not 'updated', for new services). Service was deleted between register and update. Wrong namespace/group/service name. Ephemeral/persistent flag mismatch — the service was registered with a different ephemeral value than the instance.

Related errors

• 20004
• 10000
• 400
• WEIGHT_ERROR
• PARAMETER_VALIDATE_ERROR

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