alibaba/nacos · error · NacosApiException

CONFLICT

CONFLICT

Error message

mcp server `%s` has existed, please update it rather than create.

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/McpServerOperationService.java:391

    /**
     * Create new mcp server with resource specification.
     *
     * @param namespaceId namespace id of mcp server
     * @param serverSpecification mcp server specification
     * @param toolSpecification mcp server tool specification
     * @param resourceSpecification mcp server resource specification
     * @param endpointSpecification mcp server endpoint specification
     * @return mcp server id
     * @throws NacosException any exception during handling
     */
    public String createMcpServer(String namespaceId, McpServerBasicInfo serverSpecification,
        McpToolSpecification toolSpecification, McpResourceSpecification resourceSpecification,
        McpEndpointSpec endpointSpecification) throws NacosException {
        
        String existId =
            resolveMcpServerId(namespaceId, serverSpecification.getName(), StringUtils.EMPTY);
        if (StringUtils.isNotEmpty(existId)) {
            throw new NacosApiException(NacosApiException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,
                String.format("mcp server `%s` has existed, please update it rather than create.",
                    serverSpecification.getName()));
        }
        
        ServerVersionDetail versionDetail = serverSpecification.getVersionDetail();
        if (null == versionDetail && StringUtils.isNotBlank(serverSpecification.getVersion())) {
            versionDetail = new ServerVersionDetail();
            versionDetail.setVersion(serverSpecification.getVersion());
            serverSpecification.setVersionDetail(versionDetail);
        }
        if (Objects.isNull(versionDetail) || StringUtils.isEmpty(versionDetail.getVersion())) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Version must be specified in parameter `serverSpecification`");
        }
        String id;
        String customMcpId = serverSpecification.getId();

View on GitHub (pinned to 9b989acdf1)

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.

Example fix

// before
String id = service.createMcpServer(ns, spec, tools, resources, endpoint);

// after
String existingId = service.resolveMcpServerId(ns, spec.getName(), "");
if (StringUtils.isNotEmpty(existingId)) {
    spec.setId(existingId);
    service.updateMcpServer(ns, spec, tools, resources, endpoint, false);
} else {
    String id = service.createMcpServer(ns, spec, tools, resources, endpoint);
}

Defensive patterns

Strategy: validation

Validate before calling

// Check existence by name before creating
String existId = mcpServerOperationService.resolveMcpServerId(namespaceId, spec.getName(), StringUtils.EMPTY);
if (StringUtils.isNotEmpty(existId)) {
    spec.setId(existId);
    mcpServerOperationService.updateMcpServer(namespaceId, spec, ...);
} else {
    mcpServerOperationService.createMcpServer(namespaceId, spec, ...);
}

Type guard

public static boolean mcpServerNameExists(
        McpServerOperationService svc, String namespaceId, String name) {
    return StringUtils.isNotEmpty(
        svc.resolveMcpServerId(namespaceId, name, StringUtils.EMPTY));
}

Try / catch

try {
    service.createMcpServer(ns, spec, tools, resources, endpoint);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.RESOURCE_CONFLICT.getCode()) {
        spec.setId(service.resolveMcpServerId(ns, spec.getName(), StringUtils.EMPTY));
        service.updateMcpServer(ns, spec, tools, resources, endpoint, false);
    } else {
        throw e;
    }
}

Prevention

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.

When it happens

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

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

Related errors

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