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

Source

Thrown at plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/mcp/McpRegistryClient.java:111

        return fetchUrlPage(endpoint, cursor, limit, search);
    }
    
    McpServerDetailInfo fetchOfficialRegistryServer(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;
        Page page = fetchOfficialRegistryPage(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 Page fetchUrlPage(String urlData, String cursor, Integer limit, String search)
        throws Exception {
        String pageUrl = buildPageUrl(urlData.trim(), cursor, limit, search);
        ImportHttpResponse response =
            httpClient.get(pageUrl, READ_TIMEOUT_SECONDS, HEADER_ACCEPT_JSON);
        int code = response.getStatusCode();
        if (!isSuccessStatus(code)) {
            throw new IllegalStateException("HTTP " + code + " when fetching " + pageUrl);
        }
        try {
            McpRegistryServerList listPage =
                JacksonUtils.toObj(response.getBody(), McpRegistryServerList.class);
            List<McpServerDetailInfo> servers = Collections.emptyList();
            String next = null;
            if (listPage != null && listPage.getServers() != null) {
                servers = listPage.getServers().stream()

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Confirm the externalId by listing/searching the registry first and copying the exact id or name.
  2. Increase the limit parameter so the target server is within the fetched page.
  3. If the server was removed, choose a current entry from the registry search results.

Example fix

// before
client.fetchOfficialRegistryServer("old-or-typo-id", 30);

// after
Page page = client.fetchOfficialRegistryPage(null, 30, "correct-name");
String id = page.getServers().get(0).getId();
client.fetchOfficialRegistryServer(id, 30);
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check: ensure the id appears in a fresh search page.
Page page = client.fetchOfficialRegistryPage(null, Math.max(limit, 30), externalId);
boolean exists = page.getServers().stream()
    .anyMatch(s -> externalId.equals(s.getName()) || externalId.equals(s.getId()));
if (!exists) {
    throw new NoSuchElementException("No MCP server matching: " + externalId);
}

Try / catch

try {
    McpServerDetailInfo info = client.fetchOfficialRegistryServer(externalId, limit);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("not found in registry")) {
        // re-search and prompt user to pick a valid id
    }
    throw e;
}

Prevention

When it happens

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

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

Related errors

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