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.

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)

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.