alibaba/nacos · error · IllegalStateException

HTTP + code + when fetching + pageUrl

Error message

HTTP  + code +  when fetching  + pageUrl

What it means

Thrown by McpRegistryClient.fetchUrlPage() as an IllegalStateException when the HTTP GET to the official MCP registry endpoint returns a non-success status code. The message includes the status code and the full URL attempted, aiding diagnosis.

Solutions

  1. Verify the configured MCP registry endpoint URL is correct and reachable (curl the URL directly).
  2. Check the registry service health / status page and retry transient 5xx/429 errors.
  3. For persistent 4xx, correct the endpoint configuration; for 5xx, retry with backoff.

Example fix

// before
nacos.ai.mcp.registry.endpoint=https://registry.example.invalid/api

// after
nacos.ai.mcp.registry.endpoint=https://registry.example.com/api
Defensive patterns

Strategy: retry

Validate before calling

// Validate the registry endpoint is reachable before importing.
ImportHttpResponse probe = httpClient.get(endpoint, READ_TIMEOUT_SECONDS, HEADER_ACCEPT_JSON);
if (!probe.isSuccess()) {
    throw new IllegalStateException("Registry endpoint unhealthy: HTTP " + probe.getStatusCode());
}

Try / catch

int maxRetries = 3;
for (int attempt = 1; attempt <= maxRetries; attempt++) {
    try {
        return client.fetchOfficialRegistryPage(cursor, limit, search);
    } catch (IllegalStateException e) {
        if (!e.getMessage().startsWith("HTTP") || attempt == maxRetries) throw e;
        // transient 5xx/429 — back off and retry
    }
}

Prevention

When it happens

Trigger: httpClient.get(pageUrl, READ_TIMEOUT_SECONDS, HEADER_ACCEPT_JSON) returns a response whose status code is not in the success range (isSuccessStatus(code) is false); e.g., 404 for a wrong endpoint, 401 for an auth-required registry, 5xx for a registry outage, or a timeout-mapped code.

Common situations: Misconfigured registry endpoint URL; registry service temporarily down or rate-limiting (429); network proxy/firewall returning an error page; SSL/TLS handshake failure surfaced as a non-2xx.

Related errors

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

Appendix: source

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

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

View on GitHub (pinned to 9b989acdf1)