alibaba/nacos · warning · NacosApiException

21007

21007

Error message

specified service %s already exists!

What it means

Thrown by ServiceOperatorV2Impl.create when ServiceManager already contains a singleton for the given Service. Error code 21007 maps to ErrorCode.SERVICE_ALREADY_EXIST with NacosException.INVALID_PARAM (400). The service is keyed by (namespace, group, name), so any pre-existing service with that exact triple blocks creation.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/core/ServiceOperatorV2Impl.java:97

    
    @Override
    public void create(String namespaceId, String serviceName, ServiceMetadata metadata)
        throws NacosException {
        Service service =
            getServiceFromGroupedServiceName(namespaceId, serviceName, metadata.isEphemeral());
        create(service, metadata);
    }
    
    /**
     * Create new service.
     *
     * @param service  v2 service
     * @param metadata new metadata of service
     * @throws NacosException nacos exception during creating
     */
    public void create(Service service, ServiceMetadata metadata) throws NacosException {
        if (ServiceManager.getInstance().containSingleton(service)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.SERVICE_ALREADY_EXIST,
                String.format("specified service %s already exists!",
                    service.getGroupedServiceName()));
        }
        metadataOperateService.updateServiceMetadata(service, metadata);
    }
    
    @Override
    public void update(Service service, ServiceMetadata metadata) throws NacosException {
        if (!ServiceManager.getInstance().containSingleton(service)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.SERVICE_NOT_EXIST,
                String.format("service %s not found!", service.getGroupedServiceName()));
        }
        metadataOperateService.updateServiceMetadata(service, metadata);
        NotifyCenter.publishEvent(new InfoChangeEvent.ServiceInfoChangeEvent(service));
    }
    
    @Override

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Check ServiceManager.getInstance().containSingleton(service) or query the service API before calling create.
  2. Make provisioning scripts idempotent: treat SERVICE_ALREADY_EXIST (21007) as success.
  3. If the service is stale, delete it first (after unregistering all instances) then recreate.
  4. Use a guard: create-or-update semantics instead of bare create.

Example fix

// before
serviceOperatorV2.create(service, metadata);

// after — idempotent create
if (!ServiceManager.getInstance().containSingleton(service)) {
    serviceOperatorV2.create(service, metadata);
}
Defensive patterns

Strategy: validation

Validate before calling

Service service = Service.newService(namespaceId, groupName, serviceName, ephemeral);
if (ServiceManager.getInstance().containSingleton(service)) {
    // already exists — skip create or treat as success
    return;
}
serviceOperatorV2.create(service, metadata);

Try / catch

try {
    serviceOperatorV2.create(service, metadata);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM
            && ErrorCode.SERVICE_ALREADY_EXIST.getCode() == 21007) {
        // idempotent: already created, continue
    } else throw e;
}

Prevention

When it happens

Trigger: Calling the create-service API (POST /v3/admin/ns/service or equivalent) for a (namespaceId, groupName, serviceName) triple that already has a registered singleton. Happens during automated provisioning scripts that create services idempotently without first checking existence, or during retry after a partial failure.

Common situations: Deployment automation re-running a create-service step. A previous create succeeded but the caller did not receive the response (network timeout) and retried. Two concurrent create requests for the same service. Service exists from a prior application lifecycle and was never cleaned up.

Related errors

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