alibaba/nacos · error · NacosApiException

INVALID_PARAM

INVALID_PARAM

Error message

Version must be specified in parameter `serverSpecification`

What it means

Thrown by createMcpServer when neither serverSpecification.getVersionDetail() nor serverSpecification.getVersion() provides a non-blank version string. Nacos requires every MCP server to declare at least one version, so an absent version is a hard validation failure during create.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/McpServerOperationService.java:403

        McpToolSpecification toolSpecification, McpResourceSpecification resourceSpecification,
        McpEndpointSpec endpointSpecification) throws NacosException {
        
        String existId =
            resolveMcpServerId(namespaceId, serverSpecification.getName(), StringUtils.EMPTY);
        if (StringUtils.isNotEmpty(existId)) {
            throw new NacosApiException(NacosApiException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,
                String.format("mcp server `%s` has existed, please update it rather than create.",
                    serverSpecification.getName()));
        }
        
        ServerVersionDetail versionDetail = serverSpecification.getVersionDetail();
        if (null == versionDetail && StringUtils.isNotBlank(serverSpecification.getVersion())) {
            versionDetail = new ServerVersionDetail();
            versionDetail.setVersion(serverSpecification.getVersion());
            serverSpecification.setVersionDetail(versionDetail);
        }
        if (Objects.isNull(versionDetail) || StringUtils.isEmpty(versionDetail.getVersion())) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Version must be specified in parameter `serverSpecification`");
        }
        String id;
        String customMcpId = serverSpecification.getId();
        
        if (StringUtils.isEmpty(customMcpId)) {
            id = UUID.randomUUID().toString();
        } else {
            if (!StringUtils.isUuidString(customMcpId)) {
                throw new NacosApiException(NacosApiException.INVALID_PARAM,
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "parameter `serverSpecification.id` is not match uuid pattern,  must obey uuid pattern");
            }
            if (mcpServerIndex.getMcpServerById(serverSpecification.getId()) != null) {
                throw new NacosApiException(NacosApiException.INVALID_PARAM,
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "parameter `serverSpecification.id` conflict with exist mcp server id");

View on GitHub (pinned to 9b989acdf1)

Solutions

Set spec.setVersion("1.0.0") or spec.setVersionDetail(new ServerVersionDetail with version) before calling createMcpServer.
Validate the spec fields client-side before sending: reject if both version and versionDetail.version are blank.
If using JSON deserialization, ensure the payload includes a non-empty 'version' or 'versionDetail.version' field.

Example fix

// before
McpServerBasicInfo spec = new McpServerBasicInfo();
spec.setName("my-mcp");
// version forgotten
service.createMcpServer(ns, spec, ...);

// after
McpServerBasicInfo spec = new McpServerBasicInfo();
spec.setName("my-mcp");
spec.setVersion("1.0.0");
service.createMcpServer(ns, spec, ...);

Defensive patterns

Strategy: validation

Validate before calling

// Validate version before calling createMcpServer
if (spec.getVersionDetail() == null && StringUtils.isBlank(spec.getVersion())) {
    throw new IllegalArgumentException("MCP server version is required");
}
service.createMcpServer(ns, spec, tools, resources, endpoint);

Type guard

public static boolean hasValidVersion(McpServerBasicInfo spec) {
    if (spec.getVersionDetail() != null
            && StringUtils.isNotBlank(spec.getVersionDetail().getVersion())) {
        return true;
    }
    return StringUtils.isNotBlank(spec.getVersion());
}

Try / catch

try {
    service.createMcpServer(ns, spec, ...);
} catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()
            && e.getMessage().contains("Version must be specified")) {
        spec.setVersion("1.0.0");
        service.createMcpServer(ns, spec, ...);
    } else {
        throw e;
    }
}

Prevention

Always set spec.setVersion("1.0.0") as a default in your spec builder.
Add a pre-flight validation method that checks all required fields.
When deserializing from JSON, use strict schemas that require 'version'.

When it happens

Trigger: Calling createMcpServer with a McpServerBasicInfo whose versionDetail is null and version field is blank or null. Also triggered when versionDetail is present but its getVersion() returns empty.

Common situations: Deserialization gap where the JSON payload omits 'version' or 'versionDetail'. Using a shared spec builder that forgot to set the version. Copying a spec object from a template that was not fully populated.

Related errors

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