alibaba/nacos · error · NacosApiException

NOT_FOUND

NOT_FOUND

Error message

mcp server `%s` for version `%s` not found

What it means

Thrown by McpServerOperationService.getMcpServerDetail when the MCP server version exists in the version index but the specific version's detail config is not found (config query returns CONFIG_NOT_FOUND status). Returns NOT_FOUND with MCP_SEVER_VERSION_NOT_FOUND detail, naming the server id and version.

Source

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

     * @return detail info with {@link McpServerDetailInfo}
     * @throws NacosException any exception during handling
     */
    public McpServerDetailInfo getMcpServerDetail(String namespaceId, String mcpServerId,
        String mcpServerName,
        String version) throws NacosException {
        mcpServerId = resolveMcpServerId(namespaceId, mcpServerName, mcpServerId);
        
        McpServerVersionInfo mcpServerVersionInfo =
            getMcpServerVersionInfo(namespaceId, mcpServerId);
        if (StringUtils.isEmpty(version)) {
            version = mcpServerVersionInfo.getLatestPublishedVersion();
        }
        
        ConfigQueryChainRequest request =
            buildQueryMcpServerRequest(namespaceId, mcpServerId, version);
        ConfigQueryChainResponse response = configQueryChainService.handle(request);
        if (McpConfigUtils.isConfigNotFound(response.getStatus())) {
            throw new NacosApiException(NacosApiException.NOT_FOUND,
                ErrorCode.MCP_SEVER_VERSION_NOT_FOUND,
                String.format("mcp server `%s` for version `%s` not found", mcpServerId, version));
        }
        
        McpServerStorageInfo serverSpecification = JacksonUtils.toObj(response.getContent(),
            McpServerStorageInfo.class);
        
        McpServerDetailInfo result = new McpServerDetailInfo();
        result.setId(mcpServerId);
        BeanUtils.copyProperties(serverSpecification, result);
        result.setNamespaceId(namespaceId);
        
        List<ServerVersionDetail> versionDetails = mcpServerVersionInfo.getVersionDetails();
        String latestVersion = mcpServerVersionInfo.getLatestPublishedVersion();
        for (ServerVersionDetail versionDetail : versionDetails) {
            versionDetail.setIs_latest(versionDetail.getVersion().equals(latestVersion));
        }
        result.setAllVersions(mcpServerVersionInfo.getVersionDetails());

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Omit the version parameter to fetch the latestPublishedVersion automatically.
2. List available versions first (McpServerVersionInfo.versionDetails) and request one that exists.
3. If the version detail is genuinely missing, republish that version or remove the stale version entry.

Example fix

// before
service.getMcpServerDetail(ns, id, name, "9.9.9"); // unpublished version -> not found

// after
// omit version to get latest published detail
service.getMcpServerDetail(ns, id, name, null);

McpServerVersionInfo info = service.getMcpServerVersionInfo(ns, id);
Set<String> versions = info.getVersionDetails().stream().map(ServerVersionDetail::getVersion).collect(Collectors.toSet());
if (!versions.contains(version)) throw new IllegalArgumentException("version not published: " + version);

boolean versionExists(McpServerVersionInfo info, String v) {
    return info.getVersionDetails().stream().anyMatch(d -> Objects.equals(d.getVersion(), v));
}

try { service.getMcpServerDetail(ns, id, name, version); }
catch (NacosApiException e) { if (e.getDetailErrCode() == ErrorCode.MCP_SEVER_VERSION_NOT_FOUND.getCode()) { service.getMcpServerDetail(ns, id, name, null); } }

When it happens

Trigger: Requesting detail for an MCP server with a version that was never published or whose detail config was deleted/lost, while the version info (McpServerVersionInfo) still exists. Also fires when an explicit version arg resolves to a non-existent config.

Common situations: Requesting a draft/unpublished version; the version detail config was removed but the version-list entry remains; passing a version that does not match any published version; data inconsistency after a failed publish.

Related errors

• NOT_FOUND
• MCP server not found in registry: ${externalId}
• 50100
• MCP server not found in registry: + externalId
• 10000

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