{"record":{"id":"28e6d732000d90c1","repo":"alibaba/nacos","slug":"mcp-server-not-found-in-registry-externalid","errorCode":null,"errorMessage":"MCP server not found in registry: ${externalId}","messagePattern":"MCP server not found in registry: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/McpExternalDataAdaptor.java","lineNumber":170,"sourceCode":"     * @return adapted MCP server detail\n     * @throws Exception if registry fetch or adaptation failed\n     */\n    public McpServerDetailInfo fetchOfficialRegistryServer(String urlData, String externalId,\n        int limit) 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        UrlPageResult page = fetchOfficialRegistryPage(urlData, 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 UrlPageResult fetchUrlPage(String urlData, String cursor, Integer limit, String search)\n        throws Exception {\n        String base = urlData.trim();\n        HttpClient client = getHttpClient();\n        String pageUrl = buildPageUrl(base, cursor, limit, search);\n        HttpRequest request = buildGetRequest(pageUrl);\n        HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());\n        int code = resp.statusCode();\n        if (!isSuccessStatus(code)) {\n            throw new IllegalStateException(\"HTTP \" + code + \" when fetching \" + pageUrl);\n        }\n        List<McpServerDetailInfo> servers = null;\n        String next = null;\n        try {\n            McpRegistryServerList listPage =\n                JacksonUtils.toObj(resp.body(), McpRegistryServerList.class);","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/McpExternalDataAdaptor.java#L152-L188","documentation":"Thrown by McpExternalDataAdaptor.fetchOfficialRegistryServer when the registry page was fetched successfully but no server matched the requested externalId by name or generated id. It is an IllegalStateException indicating the resource exists in the broader registry context but was not on the returned page.","triggerScenarios":"A registry page is returned with servers, but none has a name or id equal to externalId. Also possible if the search parameter did not narrow the page to the target, or the id is stale/renamed.","commonSituations":"The server was renamed or removed upstream in the registry; pagination/search limit excluded the target from the first page; the externalId was constructed with a different naming convention than the registry uses.","solutions":["Verify the externalId matches a current server name or id in the registry.","Increase the limit or use the fetch-all path to ensure the target appears on a page.","Re-fetch the registry listing to refresh ids before selecting one."],"exampleFix":"// before\nadaptor.fetchOfficialRegistryServer(registryUrl, \"old-name\", 30); // renamed upstream\n\n// after\n// refresh listing first, then look up by current id\nList<McpServerDetailInfo> all = adaptor.adaptOfficialRegistryUrl(registryUrl, null, -1, null);\nString id = all.stream().filter(s -> s.getName().equals(\"new-name\")).findFirst().get().getId();\nadaptor.fetchOfficialRegistryServer(registryUrl, id, 30);","handlingStrategy":"try-catch","validationCode":"List<McpServerDetailInfo> page = adaptor.adaptOfficialRegistryUrl(url, null, -1, externalId);\nboolean exists = page.stream().anyMatch(s -> Objects.equals(s.getName(), externalId) || Objects.equals(s.getId(), externalId));\nif (!exists) { throw new IllegalStateException(\"not found: \" + externalId); }","typeGuard":"boolean registryHasId(List<McpServerDetailInfo> all, String id) {\n    return all.stream().anyMatch(s -> Objects.equals(s.getName(), id) || Objects.equals(s.getId(), id));\n}","tryCatchPattern":"try { adaptor.fetchOfficialRegistryServer(url, id, limit); }\ncatch (IllegalStateException e) { refreshRegistryIds(); }","preventionTips":["Refresh the registry listing before resolving an id.","Use fetch-all (-1 limit) when correctness matters more than latency."],"tags":["mcp","registry","import","not-found","illegal-state"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}