alibaba/nacos · error · NacosApiException

INVALID_PARAM

INVALID_PARAM

Error message

`namespaceId`, `groupName`, `serviceName` should be in remoteServerConfig data if type is `REF`

What it means

Thrown by McpEndpointOperationService when an MCP server endpoint spec has type REF but the `data` map is missing `namespaceId`, `groupName`, or `serviceName`. A REF endpoint points at an already-existing Nacos naming service, so all three coordinates must be supplied. Returns INVALID_PARAM with PARAMETER_MISSING detail.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/McpEndpointOperationService.java:86

     *
     * @param namespaceId           namespace id of mcp server
     * @param mcpName               name of mcp server
     * @param endpointSpecification mcp server endpoint specification, see {@link McpEndpointSpec}
     * @param overrideExisting       if replace all the instances when update the mcp server
     * @return {@link Service}
     * @throws NacosException any exception during handling
     */
    public Service createMcpServerEndpointServiceIfNecessary(String namespaceId, String mcpName,
        String version,
        McpEndpointSpec endpointSpecification, boolean overrideExisting) throws NacosException {
        if (AiConstants.Mcp.MCP_ENDPOINT_TYPE_REF
            .equalsIgnoreCase(endpointSpecification.getType())) {
            Map<String, String> endpointServiceData = endpointSpecification.getData();
            if (!endpointServiceData.containsKey(CommonParams.NAMESPACE_ID)
                || !endpointServiceData.containsKey(
                    CommonParams.GROUP_NAME)
                || !endpointServiceData.containsKey(CommonParams.SERVICE_NAME)) {
                throw new NacosApiException(NacosApiException.INVALID_PARAM,
                    ErrorCode.PARAMETER_MISSING,
                    "`namespaceId`, `groupName`, `serviceName` should be in remoteServerConfig data if type is `REF`");
            }
            String refGroupName = endpointSpecification.getData().get(CommonParams.GROUP_NAME);
            String refServiceName = endpointSpecification.getData().get(CommonParams.SERVICE_NAME);
            return Service.newService(namespaceId, refGroupName, refServiceName);
        }
        String versionMcpName = mcpName + "::" + version;
        Service service = generateService(namespaceId, versionMcpName);
        if (isNotExist(service)) {
            doCreateNewService(service);
            doUpdateInstanceInfo(service, endpointSpecification, namespaceId, mcpName,
                overrideExisting, versionMcpName);
            return service;
        }
        doUpdateInstanceInfo(service, endpointSpecification, namespaceId, mcpName, overrideExisting,
            versionMcpName);
        return service;

View on GitHub (pinned to 9b989acdf1)

Solutions

When type is REF, put namespaceId, groupName, and serviceName into McpEndpointSpec.data.
Use the exact CommonParams key strings (namespaceId, groupName, serviceName).
Validate the three keys are present client-side before calling createMcpServer/updateMcpServer.

Example fix

// before
McpEndpointSpec spec = new McpEndpointSpec();
spec.setType("REF");
spec.getData().put("groupName", "DEFAULT_GROUP"); // namespaceId/serviceName missing

// after
Map<String,String> data = spec.getData();
data.put("namespaceId", "public");
data.put("groupName", "DEFAULT_GROUP");
data.put("serviceName", "my-mcp-backend");

Defensive patterns

Strategy: validation

Validate before calling

if ("REF".equalsIgnoreCase(spec.getType())) {
    Map<String,String> d = spec.getData();
    if (!d.containsKey("namespaceId") || !d.containsKey("groupName") || !d.containsKey("serviceName")) {
        throw new IllegalArgumentException("REF endpoint needs namespaceId, groupName, serviceName");
    }
}

Type guard

boolean isCompleteRef(McpEndpointSpec s) {
    Map<String,String> d = s.getData();
    return d != null && d.containsKey("namespaceId") && d.containsKey("groupName") && d.containsKey("serviceName");
}

Try / catch

try { operationService.createMcpServer(...); }
catch (NacosApiException e) { if (e.getDetailErrCode() == ErrorCode.PARAMETER_MISSING.getCode()) { /* fix ref data */ } }

Prevention

When using REF endpoints, fill all three CommonParams keys from a service picker.
Validate ref completeness in the form/controller before reaching the service.

When it happens

Trigger: Creating/updating an MCP server whose McpEndpointSpec.type is 'REF' while endpointSpecification.getData() omits any of CommonParams.NAMESPACE_ID, GROUP_NAME, or SERVICE_NAME.

Common situations: Switching an MCP server from a direct (stdio/http) endpoint to a REF endpoint without filling all reference fields; typo in the data map keys; frontend form submits only partial ref data.

Related errors

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