{"record":{"id":"267192498b72270f","repo":"alibaba/nacos","slug":"http-code-when-fetching-pageurl","errorCode":null,"errorMessage":"HTTP ${code} when fetching ${pageUrl}","messagePattern":"HTTP (.+?) when fetching (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/McpExternalDataAdaptor.java","lineNumber":182,"sourceCode":"                if (StringUtils.equals(externalId, each.getName())\n                    || StringUtils.equals(externalId, each.getId())) {\n                    return each;\n                }\n            }\n        }\n        throw new IllegalStateException(\"MCP server not found in registry: \" + externalId);\n    }\n    \n    private UrlPageResult fetchUrlPage(String urlData, String cursor, Integer limit, String search)\n        throws Exception {\n        String base = urlData.trim();\n        HttpClient client = getHttpClient();\n        String pageUrl = buildPageUrl(base, cursor, limit, search);\n        HttpRequest request = buildGetRequest(pageUrl);\n        HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());\n        int code = resp.statusCode();\n        if (!isSuccessStatus(code)) {\n            throw new IllegalStateException(\"HTTP \" + code + \" when fetching \" + pageUrl);\n        }\n        List<McpServerDetailInfo> servers = null;\n        String next = null;\n        try {\n            McpRegistryServerList listPage =\n                JacksonUtils.toObj(resp.body(), McpRegistryServerList.class);\n            if (listPage != null && listPage.getServers() != null) {\n                servers = listPage.getServers().stream()\n                    .map(this::adaptOfficialMcpServerFromResponse)\n                    .collect(Collectors.toList());\n            }\n            if (listPage != null && listPage.getMetadata() != null) {\n                next = listPage.getMetadata().getNextCursor();\n            }\n        } catch (Exception e) {\n            throw new IllegalStateException(\"Failed to parse response body\", e);\n        }\n        return new UrlPageResult(servers, next);","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/McpExternalDataAdaptor.java#L164-L200","documentation":"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.","triggerScenarios":"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.","commonSituations":"Wrong or outdated registry base URL; registry maintenance/outage; rate limiting (429); corporate proxy blocking the request; mistyped path producing 404.","solutions":["Verify the registry base URL is correct and reachable (curl it directly).","Retry after confirming transient registry errors (5xx, 429) subside.","Add auth headers or fix proxy configuration if 401/403/407 is returned."],"exampleFix":"// before\nString url = \"https://registry.example.com/v0/servers\"; // wrong path -> 404\n\n// after\nString url = \"https://registry.modelcontextprotocol.org/v0/servers\"; // correct base","handlingStrategy":"retry","validationCode":"if (!URI.create(url).isAbsolute()) { throw new IllegalArgumentException(\"registry URL must be absolute\"); }","typeGuard":"boolean isAbsoluteUrl(String u) { try { return URI.create(u).isAbsolute(); } catch (Exception e) { return false; } }","tryCatchPattern":"try { adaptor.fetchOfficialRegistryPage(url, c, l, s); }\ncatch (IllegalStateException e) { if (isTransient(e)) retryWithBackoff(); else reportRegistryDown(); }","preventionTips":["Verify the registry base URL is reachable before bulk imports.","Treat 5xx/429 as transient with bounded retry; treat 4xx as configuration errors."],"tags":["mcp","registry","network","http","illegal-state"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}