alibaba/nacos · warning · NacosApiException

MCP_SERVER_VERSION_EXIST

MCP_SERVER_VERSION_EXIST

Error message

Mcp Server %s and target version %s already exist, do not do release

What it means

Thrown by ReleaseMcpServerRequestHandler.doHandler() when the MCP server already exists AND the target version already exists. doHandler first calls getMcpServerDetail to probe; if both server and version resolve, it throws MCP_SERVER_VERSION_EXIST (CONFLICT). The surrounding catch block then routes MCP_SERVER_NOT_FOUND to create-new and MCP_SEVER_VERSION_NOT_FOUND to new-version, but VERSION_EXIST matches neither and is rethrown, ultimately landing in the response error info.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/remote/handler/ReleaseMcpServerRequestHandler.java:130

        throws NacosException {
        String namespaceId = request.getNamespaceId();
        McpServerBasicInfo serverSpecification = request.getServerSpecification();
        LOGGER.info(
            "Release new mcp server {}, version {} into namespaceId {} from connectionId {}.",
            serverSpecification.getName(), serverSpecification.getVersionDetail().getVersion(),
            namespaceId,
            meta.getConnectionId());
        ReleaseMcpServerResponse response = new ReleaseMcpServerResponse();
        try {
            // mcp server and version found, means this version of mcp server has been release, throw exception.
            McpServerBasicInfo existMcpServer =
                mcpServerOperationService.getMcpServerDetail(namespaceId,
                    serverSpecification.getId(), serverSpecification.getName(),
                    serverSpecification.getVersionDetail().getVersion());
            String version = existMcpServer.getVersionDetail().getVersion();
            LOGGER.info("Mcp Server {} and target version {} already exist.",
                existMcpServer.getName(), version);
            throw new NacosApiException(NacosException.CONFLICT, ErrorCode.MCP_SERVER_VERSION_EXIST,
                String.format(
                    "Mcp Server %s and target version %s already exist, do not do release",
                    existMcpServer.getName(), version));
        } catch (NacosApiException e) {
            if (ErrorCode.MCP_SERVER_NOT_FOUND.getCode() == e.getDetailErrCode()) {
                // mcp server not found, create new mcp server.
                String mcpId = createNewMcpServer(namespaceId, request);
                response.setMcpId(mcpId);
                LOGGER.info("Mcp Server {} released, Mcp Server id: {}",
                    serverSpecification.getName(), mcpId);
            } else if (ErrorCode.MCP_SEVER_VERSION_NOT_FOUND.getCode() == e.getDetailErrCode()) {
                // mcp server found but version not found, update mcp server.
                createNewVersionMcpServer(namespaceId, request);
                McpServerIndexData mcpServerIndexData =
                    mcpServerIndex.getMcpServerByName(namespaceId,
                        serverSpecification.getName());
                response.setMcpId(mcpServerIndexData.getId());
                LOGGER.info("Mcp Server {} new version {} released, Mcp Server id: {}",

View on GitHub (pinned to 9b989acdf1)

Solutions

Bump the versionDetail.version to a new value if you intend a new release.
If the version is intentionally the same, treat this response as success (the server+version is already present) and skip re-release.
Use the update MCP server API instead of release when you want to change an existing version in place.

Example fix

// before: re-releasing the same version
spec.getVersionDetail().setVersion("1.0.0"); // already released

// after: bump version for a new release
spec.getVersionDetail().setVersion("1.0.1");
// or, if no change is needed, treat the CONFLICT response as a no-op success.

Defensive patterns

Strategy: try-catch

Validate before calling

// Probe before releasing to avoid the CONFLICT
McpServerBasicInfo existing;
try {
    existing = mcpServerOperationService.getMcpServerDetail(namespaceId,
        spec.getId(), spec.getName(), spec.getVersionDetail().getVersion());
} catch (NacosApiException e) { /* not found is expected for a new release */ existing = null; }
if (existing != null) { /* already released; skip or bump version */ }

Try / catch

ReleaseMcpServerResponse resp = handler.handle(request, meta);
if (ErrorCode.MCP_SERVER_VERSION_EXIST.getCode() == resp.getDetailErrCode()) {
    // idempotent: version already published. Treat as success or bump version.
    return IdempotentResult.alreadyPresent(resp);
}

Prevention

Make release pipelines idempotent: treat MCP_SERVER_VERSION_EXIST as success when no change is intended.
Bump the version string for every distinct release.
Avoid blind retries of the whole release after a partial success; probe first.

When it happens

Trigger: A ReleaseMcpServerRequest whose serverSpecification name/id and versionDetail.version exactly match an already-released MCP server version. Replaying the same release request, or a CI pipeline re-publishing without bumping the version.

Common situations: Idempotent re-deploy that did not change the version; a release pipeline that retries after a partial success; duplicate concurrent release requests for the same version; the version was published manually via console and the automated deploy runs again.

Related errors

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