alibaba/nacos · error · IllegalStateException

HTTP ${code} when fetching ${pageUrl}

Error message

HTTP ${code} when fetching ${pageUrl}

What it means

Thrown by McpExternalDataAdaptor.fetchUrlPage when the HTTP response status from the MCP registry endpoint is outside the 200-299 success range. The message includes the status code and the full requested URL. It is an IllegalStateException.

Source

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

                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);
            if (listPage != null && listPage.getServers() != null) {
                servers = listPage.getServers().stream()
                    .map(this::adaptOfficialMcpServerFromResponse)
                    .collect(Collectors.toList());
            }
            if (listPage != null && listPage.getMetadata() != null) {
                next = listPage.getMetadata().getNextCursor();
            }
        } catch (Exception e) {
            throw new IllegalStateException("Failed to parse response body", e);
        }
        return new UrlPageResult(servers, next);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify the registry base URL is correct and reachable (curl it directly).
2. Retry after confirming transient registry errors (5xx, 429) subside.
3. Add auth headers or fix proxy configuration if 401/403/407 is returned.

Example fix

// before
String url = "https://registry.example.com/v0/servers"; // wrong path -> 404

// after
String url = "https://registry.modelcontextprotocol.org/v0/servers"; // correct base

if (!URI.create(url).isAbsolute()) { throw new IllegalArgumentException("registry URL must be absolute"); }

boolean isAbsoluteUrl(String u) { try { return URI.create(u).isAbsolute(); } catch (Exception e) { return false; } }

try { adaptor.fetchOfficialRegistryPage(url, c, l, s); }
catch (IllegalStateException e) { if (isTransient(e)) retryWithBackoff(); else reportRegistryDown(); }

When it happens

Trigger: The registry endpoint returns 4xx/5xx (e.g. 404 for wrong base URL, 401/403 for auth, 5xx for registry outage); network proxy returns an error page; the URL points to the wrong path.

Common situations: Wrong or outdated registry base URL; registry maintenance/outage; rate limiting (429); corporate proxy blocking the request; mistyped path producing 404.

Related errors

• MCP server not found in registry: ${externalId}
• Failed to parse response body
• Invalid URL: ${url}
• HTTP + code + when fetching + pageUrl
• 10000

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