alibaba/nacos · error · IllegalArgumentException

MCP server external id is blank

Error message

MCP server external id is blank

What it means

Thrown by McpExternalDataAdaptor.fetchOfficialRegistryServer when the externalId (server name or generated id) used to look up a single registry server is blank. The lookup needs a concrete identifier to search the registry page. It is an IllegalArgumentException.

Source

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

        if (StringUtils.isBlank(urlData)) {
            throw new IllegalArgumentException("URL is blank");
        }
        return fetchUrlPage(urlData.trim(), cursor, limit, search);
    }
    
    /**
     * Fetch one official MCP registry server by name or generated id.
     *
     * @param urlData registry endpoint
     * @param externalId selected server name or generated id
     * @param limit search page size
     * @return adapted MCP server detail
     * @throws Exception if registry fetch or adaptation failed
     */
    public McpServerDetailInfo fetchOfficialRegistryServer(String urlData, 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;
        UrlPageResult page = fetchOfficialRegistryPage(urlData, 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 UrlPageResult fetchUrlPage(String urlData, String cursor, Integer limit, String search)
        throws Exception {
        String base = urlData.trim();
        HttpClient client = getHttpClient();

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass a non-blank externalId (the server name or its generated id from the registry).
2. Validate the selected server id is non-blank before invoking the lookup.
3. Surface a clear user-facing error if no server was selected.

Example fix

// before
adaptor.fetchOfficialRegistryServer(registryUrl, "", 30); // blank id -> error

// after
adaptor.fetchOfficialRegistryServer(registryUrl, selectedServer.getId(), 30);

if (StringUtils.isBlank(externalId)) { throw new IllegalArgumentException("externalId is required"); }

boolean hasExternalId(String id) { return id != null && !id.trim().isEmpty(); }

try { adaptor.fetchOfficialRegistryServer(url, id, limit); }
catch (IllegalArgumentException e) { promptUserToSelect(); }

When it happens

Trigger: Calling fetchOfficialRegistryServer(urlData, externalId, limit) with a null/empty/whitespace externalId.

Common situations: User selection not propagated from the UI; an import flow that resolves the target server lazily but the resolution returned empty; defaulting externalId to an unset variable.

Related errors

• URL is blank
• Unsupported import type: ${externalDataTypeEnum}
• 10000
• 20002
• MCP server not found in registry: ${externalId}

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