{"record":{"id":"90272c500c08ed9c","repo":"alibaba/nacos","slug":"conflict","errorCode":"CONFLICT","errorMessage":"mcp server `%s` has existed, please update it rather than create.","messagePattern":"mcp server `(.+?)` has existed, please update it rather than create\\.","errorType":"exception","errorClass":"NacosApiException","httpStatus":409,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/McpServerOperationService.java","lineNumber":391,"sourceCode":"    /**\n     * Create new mcp server with resource specification.\n     *\n     * @param namespaceId namespace id of mcp server\n     * @param serverSpecification mcp server specification\n     * @param toolSpecification mcp server tool specification\n     * @param resourceSpecification mcp server resource specification\n     * @param endpointSpecification mcp server endpoint specification\n     * @return mcp server id\n     * @throws NacosException any exception during handling\n     */\n    public String createMcpServer(String namespaceId, McpServerBasicInfo serverSpecification,\n        McpToolSpecification toolSpecification, McpResourceSpecification resourceSpecification,\n        McpEndpointSpec endpointSpecification) throws NacosException {\n        \n        String existId =\n            resolveMcpServerId(namespaceId, serverSpecification.getName(), StringUtils.EMPTY);\n        if (StringUtils.isNotEmpty(existId)) {\n            throw new NacosApiException(NacosApiException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,\n                String.format(\"mcp server `%s` has existed, please update it rather than create.\",\n                    serverSpecification.getName()));\n        }\n        \n        ServerVersionDetail versionDetail = serverSpecification.getVersionDetail();\n        if (null == versionDetail && StringUtils.isNotBlank(serverSpecification.getVersion())) {\n            versionDetail = new ServerVersionDetail();\n            versionDetail.setVersion(serverSpecification.getVersion());\n            serverSpecification.setVersionDetail(versionDetail);\n        }\n        if (Objects.isNull(versionDetail) || StringUtils.isEmpty(versionDetail.getVersion())) {\n            throw new NacosApiException(NacosApiException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Version must be specified in parameter `serverSpecification`\");\n        }\n        String id;\n        String customMcpId = serverSpecification.getId();\n        ","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/McpServerOperationService.java#L373-L409","documentation":"Thrown by createMcpServer when resolveMcpServerId finds a non-empty existing ID for the same server name in the same namespace. Nacos prevents duplicate MCP server names per namespace, so the caller must use the update path instead of create.","triggerScenarios":"Calling createMcpServer with a server name that already exists in the target namespace. The method resolves by name (with empty version suffix) and finds a match, so it rejects the create with CONFLICT.","commonSituations":"Re-running a create script after a partial failure where the server was already persisted. Forgetting that a teammate or CI pipeline already registered the server. Using a common/generic server name that collides with an existing one.","solutions":["Switch to updateMcpServer (or the release/add-version flow) using the existing server's ID.","If you truly want a new server, choose a unique name in that namespace.","Before creating, check if the name exists via listMcpServer and branch to update when it does."],"exampleFix":"// before\nString id = service.createMcpServer(ns, spec, tools, resources, endpoint);\n\n// after\nString existingId = service.resolveMcpServerId(ns, spec.getName(), \"\");\nif (StringUtils.isNotEmpty(existingId)) {\n    spec.setId(existingId);\n    service.updateMcpServer(ns, spec, tools, resources, endpoint, false);\n} else {\n    String id = service.createMcpServer(ns, spec, tools, resources, endpoint);\n}","handlingStrategy":"validation","validationCode":"// Check existence by name before creating\nString existId = mcpServerOperationService.resolveMcpServerId(namespaceId, spec.getName(), StringUtils.EMPTY);\nif (StringUtils.isNotEmpty(existId)) {\n    spec.setId(existId);\n    mcpServerOperationService.updateMcpServer(namespaceId, spec, ...);\n} else {\n    mcpServerOperationService.createMcpServer(namespaceId, spec, ...);\n}","typeGuard":"public static boolean mcpServerNameExists(\n        McpServerOperationService svc, String namespaceId, String name) {\n    return StringUtils.isNotEmpty(\n        svc.resolveMcpServerId(namespaceId, name, StringUtils.EMPTY));\n}","tryCatchPattern":"try {\n    service.createMcpServer(ns, spec, tools, resources, endpoint);\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.RESOURCE_CONFLICT.getCode()) {\n        spec.setId(service.resolveMcpServerId(ns, spec.getName(), StringUtils.EMPTY));\n        service.updateMcpServer(ns, spec, tools, resources, endpoint, false);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Implement an upsert helper: check name existence, then create or update accordingly.","Use unique server names per namespace to avoid collisions.","In CI pipelines, make create idempotent by checking existence first."],"tags":["mcp-server","conflict","duplicate","create"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}