alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter `mcpName` not present

What it means

The `getMcpServer(String mcpName, String version)` query guard rejects a blank `mcpName` before issuing the gRPC `queryMcpServer` call. Thrown as NacosApiException with errCode=NacosException.INVALID_PARAM (400) and detailErrCode=ErrorCode.PARAMETER_MISSING (10000). It is a synchronous client-side pre-flight guard in NacosAiService: no network call is ever made. `version` is optional (null/blank = latest), but `mcpName` is mandatory.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/NacosAiService.java:189

    
    private void start() throws NacosException {
        this.grpcClient.start(this.mcpServerCacheHolder, this.agentCardCacheHolder);
        NotifyCenter.registerToPublisher(McpServerChangedEvent.class, 16384);
        NotifyCenter.registerToPublisher(PromptChangedEvent.class, 16384);
        NotifyCenter.registerToPublisher(AgentSpecChangedEvent.class, 16384);
        NotifyCenter.registerToPublisher(SkillChangedEvent.class, 16384);
        NotifyCenter.registerSubscriber(this.aiChangeNotifier);
    }
    
    @Override
    public AgentVersionDetail publishAgent(AgentPublishRequest request) throws NacosException {
        return aiClientProxy.publishAgent(AgentModelUtils.copyPublishRequest(request));
    }
    
    @Override
    public McpServerDetailInfo getMcpServer(String mcpName, String version) throws NacosException {
        if (StringUtils.isBlank(mcpName)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter `mcpName` not present");
        }
        return grpcClient.queryMcpServer(mcpName, version);
    }
    
    @Override
    public String releaseMcpServer(McpServerBasicInfo serverSpecification,
        McpToolSpecification toolSpecification,
        McpEndpointSpec endpointSpecification) throws NacosException {
        return releaseMcpServer(serverSpecification, toolSpecification, null,
            endpointSpecification);
    }
    
    @Override
    public String releaseMcpServer(McpServerBasicInfo serverSpecification,
        McpToolSpecification toolSpecification,
        McpResourceSpecification resourceSpecification, McpEndpointSpec endpointSpecification)
        throws NacosException {

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Supply a non-blank mcpName (the MCP server's registered name).
  2. Guard with StringUtils.isNotBlank(mcpName) before the call and degrade/log when blank.
  3. Fix the upstream source of the value (config file / env var / search result) if it is unexpectedly blank.

Example fix

// before
aiService.getMcpServer(mcpName, version);  // mcpName is null/blank

// after
if (StringUtils.isBlank(mcpName)) {
    throw new IllegalArgumentException("mcpName required");
}
McpServerDetailInfo info = aiService.getMcpServer(mcpName, version);
Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(mcpName)) {
    LOG.warn("Skipping MCP query: mcpName is blank");
    return null;
}
aiService.getMcpServer(mcpName, version);

Try / catch

catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.PARAMETER_MISSING.getCode()) {
        // bad caller input — do NOT retry; log and degrade
        LOG.warn("Bad AiService input: {}", e.getMessage());
        return;
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling aiService.getMcpServer(null, v), getMcpServer("", v), or getMcpServer(" ", v). Also triggered by the 1-arg convenience default getMcpServer(name) that forwards a null name.

Common situations: mcpName sourced from an unset config/env var, an empty CLI arg, or a downstream lookup (e.g. a registry search) that returned null/empty and was forwarded unchecked.

Related errors

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