alibaba/nacos · error · IllegalArgumentException
MCP server external id is blank
Error message
MCP server external id is blank
What it means
Thrown by McpRegistryClient.fetchOfficialRegistryServer() when the supplied externalId is blank (null, empty, or whitespace-only). The method requires a concrete server identifier to look up an MCP server in the official registry. It is an IllegalArgumentException thrown before any network call.
Source
Thrown at plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/mcp/McpRegistryClient.java:99
this(endpoint, new DefaultImportHttpClient(httpClient));
}
McpRegistryClient(String endpoint, DefaultImportHttpClient httpClient) {
if (StringUtils.isBlank(endpoint)) {
throw new IllegalArgumentException("URL is blank");
}
this.endpoint = endpoint.trim();
this.httpClient = httpClient;
}
Page fetchOfficialRegistryPage(String cursor, Integer limit, String search) throws Exception {
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 =View on GitHub (pinned to 9b989acdf1)
Solutions
- Pass a non-blank externalId — the server name or registry id from a prior search() call.
- Validate externalId with StringUtils.isBlank() before invoking the importer and reject early in the UI.
- Ensure the import request payload includes the externalId field.
Example fix
// before
client.fetchOfficialRegistryServer("", 30);
// after
if (StringUtils.isBlank(externalId)) {
throw new IllegalArgumentException("externalId required");
}
client.fetchOfficialRegistryServer(externalId, 30); Defensive patterns
Strategy: validation
Validate before calling
if (com.alibaba.nacos.common.utils.StringUtils.isBlank(externalId)) {
throw new IllegalArgumentException("MCP server externalId must not be blank");
}
client.fetchOfficialRegistryServer(externalId, limit); Prevention
- Always resolve an externalId from a prior search before calling fetch.
- Reject empty selections in the UI/controller layer before reaching the importer.
- Add a null/blank check at the API boundary.
When it happens
Trigger: Calling fetchOfficialRegistryServer(externalId, limit) with externalId that is null, empty, or only spaces; typically reached via the AI registry import API when the caller omits the target server id/name.
Common situations: A console/UI import flow that submits an empty selection; a programmatic client that builds the request from an uninitialized field; an upstream parsing bug that yields a blank id.
Related errors
AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14).
Data as JSON: /api/errors/705e30c05b90f469.
Report an issue: GitHub.