{"record":{"id":"724c754ee63b32c3","repo":"alibaba/nacos","slug":"mcp-server-not-found-in-registry-externalid-724c75","errorCode":null,"errorMessage":"MCP server not found in registry:  + externalId","messagePattern":"MCP server not found in registry:  \\+ externalId","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/mcp/McpRegistryClient.java","lineNumber":111,"sourceCode":"        return fetchUrlPage(endpoint, cursor, limit, search);\n    }\n    \n    McpServerDetailInfo fetchOfficialRegistryServer(String externalId, int limit)\n        throws Exception {\n        if (StringUtils.isBlank(externalId)) {\n            throw new IllegalArgumentException(\"MCP server external id is blank\");\n        }\n        int actualLimit = limit > 0 ? limit : 30;\n        Page page = fetchOfficialRegistryPage(null, actualLimit, externalId);\n        if (CollectionUtils.isNotEmpty(page.getServers())) {\n            for (McpServerDetailInfo each : page.getServers()) {\n                if (StringUtils.equals(externalId, each.getName())\n                    || StringUtils.equals(externalId, each.getId())) {\n                    return each;\n                }\n            }\n        }\n        throw new IllegalStateException(\"MCP server not found in registry: \" + externalId);\n    }\n    \n    private Page fetchUrlPage(String urlData, String cursor, Integer limit, String search)\n        throws Exception {\n        String pageUrl = buildPageUrl(urlData.trim(), cursor, limit, search);\n        ImportHttpResponse response =\n            httpClient.get(pageUrl, READ_TIMEOUT_SECONDS, HEADER_ACCEPT_JSON);\n        int code = response.getStatusCode();\n        if (!isSuccessStatus(code)) {\n            throw new IllegalStateException(\"HTTP \" + code + \" when fetching \" + pageUrl);\n        }\n        try {\n            McpRegistryServerList listPage =\n                JacksonUtils.toObj(response.getBody(), McpRegistryServerList.class);\n            List<McpServerDetailInfo> servers = Collections.emptyList();\n            String next = null;\n            if (listPage != null && listPage.getServers() != null) {\n                servers = listPage.getServers().stream()","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/mcp/McpRegistryClient.java#L93-L129","documentation":"Thrown by McpRegistryClient.fetchOfficialRegistryServer() as an IllegalStateException when the official registry returned a page successfully but no server on that page matched the externalId by name or id. It indicates the requested MCP server does not exist in (or could not be located within) the fetched registry page.","triggerScenarios":"fetchOfficialRegistryServer queries the registry with externalId as the search term; the page comes back but none of page.getServers() has a name or id equal to externalId, so the loop falls through to the throw.","commonSituations":"A typo or stale id after a registry rename/removal; the limit was too small and the matching server was beyond the fetched page; the externalId is actually a partial/normalized name that differs from the stored value.","solutions":["Confirm the externalId by listing/searching the registry first and copying the exact id or name.","Increase the limit parameter so the target server is within the fetched page.","If the server was removed, choose a current entry from the registry search results."],"exampleFix":"// before\nclient.fetchOfficialRegistryServer(\"old-or-typo-id\", 30);\n\n// after\nPage page = client.fetchOfficialRegistryPage(null, 30, \"correct-name\");\nString id = page.getServers().get(0).getId();\nclient.fetchOfficialRegistryServer(id, 30);","handlingStrategy":"try-catch","validationCode":"// Pre-check: ensure the id appears in a fresh search page.\nPage page = client.fetchOfficialRegistryPage(null, Math.max(limit, 30), externalId);\nboolean exists = page.getServers().stream()\n    .anyMatch(s -> externalId.equals(s.getName()) || externalId.equals(s.getId()));\nif (!exists) {\n    throw new NoSuchElementException(\"No MCP server matching: \" + externalId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    McpServerDetailInfo info = client.fetchOfficialRegistryServer(externalId, limit);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"not found in registry\")) {\n        // re-search and prompt user to pick a valid id\n    }\n    throw e;\n}","preventionTips":["Always source externalId from a live search result rather than a stored/hardcoded value.","Increase the limit to ensure the target is within the fetched page.","Handle 'not found' gracefully in the UI by re-showing search results."],"tags":["ai-registry","mcp","not-found","importer"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}