alibaba/nacos · error · IllegalStateException

MCP server not found in registry: ${externalId}

Error message

MCP server not found in registry: ${externalId}

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/McpExternalDataAdaptor.java:170

     * @return adapted MCP server detail
     * @throws Exception if registry fetch or adaptation failed
     */
    public McpServerDetailInfo fetchOfficialRegistryServer(String urlData, String externalId,
        int limit) throws Exception {
        if (StringUtils.isBlank(externalId)) {
            throw new IllegalArgumentException("MCP server external id is blank");
        }
        int actualLimit = limit > 0 ? limit : 30;
        UrlPageResult page = fetchOfficialRegistryPage(urlData, null, actualLimit, externalId);
        if (CollectionUtils.isNotEmpty(page.getServers())) {
            for (McpServerDetailInfo each : page.getServers()) {
                if (StringUtils.equals(externalId, each.getName())
                    || StringUtils.equals(externalId, each.getId())) {
                    return each;
                }
            }
        }
        throw new IllegalStateException("MCP server not found in registry: " + externalId);
    }
    
    private UrlPageResult fetchUrlPage(String urlData, String cursor, Integer limit, String search)
        throws Exception {
        String base = urlData.trim();
        HttpClient client = getHttpClient();
        String pageUrl = buildPageUrl(base, cursor, limit, search);
        HttpRequest request = buildGetRequest(pageUrl);
        HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());
        int code = resp.statusCode();
        if (!isSuccessStatus(code)) {
            throw new IllegalStateException("HTTP " + code + " when fetching " + pageUrl);
        }
        List<McpServerDetailInfo> servers = null;
        String next = null;
        try {
            McpRegistryServerList listPage =
                JacksonUtils.toObj(resp.body(), McpRegistryServerList.class);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify the externalId matches a current server name or id in the registry.
2. Increase the limit or use the fetch-all path to ensure the target appears on a page.
3. Re-fetch the registry listing to refresh ids before selecting one.

Example fix

// before
adaptor.fetchOfficialRegistryServer(registryUrl, "old-name", 30); // renamed upstream

// after
// refresh listing first, then look up by current id
List<McpServerDetailInfo> all = adaptor.adaptOfficialRegistryUrl(registryUrl, null, -1, null);
String id = all.stream().filter(s -> s.getName().equals("new-name")).findFirst().get().getId();
adaptor.fetchOfficialRegistryServer(registryUrl, id, 30);

List<McpServerDetailInfo> page = adaptor.adaptOfficialRegistryUrl(url, null, -1, externalId);
boolean exists = page.stream().anyMatch(s -> Objects.equals(s.getName(), externalId) || Objects.equals(s.getId(), externalId));
if (!exists) { throw new IllegalStateException("not found: " + externalId); }

boolean registryHasId(List<McpServerDetailInfo> all, String id) {
    return all.stream().anyMatch(s -> Objects.equals(s.getName(), id) || Objects.equals(s.getId(), id));
}

try { adaptor.fetchOfficialRegistryServer(url, id, limit); }
catch (IllegalStateException e) { refreshRegistryIds(); }

When it happens

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

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

Related errors

• URL is blank
• MCP server external id is blank
• HTTP ${code} when fetching ${pageUrl}
• Failed to parse response body
• Invalid URL: ${url}

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