{"record":{"id":"529d691235310d48","repo":"alibaba/nacos","slug":"21007","errorCode":"21007","errorMessage":"specified service %s already exists!","messagePattern":"specified service (.+?) already exists!","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"warning","filePath":"naming/src/main/java/com/alibaba/nacos/naming/core/ServiceOperatorV2Impl.java","lineNumber":97,"sourceCode":"    \n    @Override\n    public void create(String namespaceId, String serviceName, ServiceMetadata metadata)\n        throws NacosException {\n        Service service =\n            getServiceFromGroupedServiceName(namespaceId, serviceName, metadata.isEphemeral());\n        create(service, metadata);\n    }\n    \n    /**\n     * Create new service.\n     *\n     * @param service  v2 service\n     * @param metadata new metadata of service\n     * @throws NacosException nacos exception during creating\n     */\n    public void create(Service service, ServiceMetadata metadata) throws NacosException {\n        if (ServiceManager.getInstance().containSingleton(service)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.SERVICE_ALREADY_EXIST,\n                String.format(\"specified service %s already exists!\",\n                    service.getGroupedServiceName()));\n        }\n        metadataOperateService.updateServiceMetadata(service, metadata);\n    }\n    \n    @Override\n    public void update(Service service, ServiceMetadata metadata) throws NacosException {\n        if (!ServiceManager.getInstance().containSingleton(service)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.SERVICE_NOT_EXIST,\n                String.format(\"service %s not found!\", service.getGroupedServiceName()));\n        }\n        metadataOperateService.updateServiceMetadata(service, metadata);\n        NotifyCenter.publishEvent(new InfoChangeEvent.ServiceInfoChangeEvent(service));\n    }\n    \n    @Override","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/core/ServiceOperatorV2Impl.java#L79-L115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check ServiceManager.getInstance().containSingleton(service) or query the service API before calling create.","Make provisioning scripts idempotent: treat SERVICE_ALREADY_EXIST (21007) as success.","If the service is stale, delete it first (after unregistering all instances) then recreate.","Use a guard: create-or-update semantics instead of bare create."],"exampleFix":"// before\nserviceOperatorV2.create(service, metadata);\n\n// after — idempotent create\nif (!ServiceManager.getInstance().containSingleton(service)) {\n    serviceOperatorV2.create(service, metadata);\n}","handlingStrategy":"validation","validationCode":"Service service = Service.newService(namespaceId, groupName, serviceName, ephemeral);\nif (ServiceManager.getInstance().containSingleton(service)) {\n    // already exists — skip create or treat as success\n    return;\n}\nserviceOperatorV2.create(service, metadata);","typeGuard":null,"tryCatchPattern":"try {\n    serviceOperatorV2.create(service, metadata);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == NacosException.INVALID_PARAM\n            && ErrorCode.SERVICE_ALREADY_EXIST.getCode() == 21007) {\n        // idempotent: already created, continue\n    } else throw e;\n}","preventionTips":["Make service-provisioning scripts idempotent by checking existence first.","Treat SERVICE_ALREADY_EXIST as success in automation.","Avoid concurrent create calls for the same service key."],"tags":["naming","service-create","already-exists","validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}