{"record":{"id":"798cd04656bdc052","repo":"alibaba/nacos","slug":"invalid-param-798cd0","errorCode":"INVALID_PARAM","errorMessage":"Version must be specified in parameter `serverSpecification`","messagePattern":"Version must be specified in parameter `serverSpecification`","errorType":"exception","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/McpServerOperationService.java","lineNumber":403,"sourceCode":"        McpToolSpecification toolSpecification, McpResourceSpecification resourceSpecification,\n        McpEndpointSpec endpointSpecification) throws NacosException {\n        \n        String existId =\n            resolveMcpServerId(namespaceId, serverSpecification.getName(), StringUtils.EMPTY);\n        if (StringUtils.isNotEmpty(existId)) {\n            throw new NacosApiException(NacosApiException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,\n                String.format(\"mcp server `%s` has existed, please update it rather than create.\",\n                    serverSpecification.getName()));\n        }\n        \n        ServerVersionDetail versionDetail = serverSpecification.getVersionDetail();\n        if (null == versionDetail && StringUtils.isNotBlank(serverSpecification.getVersion())) {\n            versionDetail = new ServerVersionDetail();\n            versionDetail.setVersion(serverSpecification.getVersion());\n            serverSpecification.setVersionDetail(versionDetail);\n        }\n        if (Objects.isNull(versionDetail) || StringUtils.isEmpty(versionDetail.getVersion())) {\n            throw new NacosApiException(NacosApiException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Version must be specified in parameter `serverSpecification`\");\n        }\n        String id;\n        String customMcpId = serverSpecification.getId();\n        \n        if (StringUtils.isEmpty(customMcpId)) {\n            id = UUID.randomUUID().toString();\n        } else {\n            if (!StringUtils.isUuidString(customMcpId)) {\n                throw new NacosApiException(NacosApiException.INVALID_PARAM,\n                    ErrorCode.PARAMETER_VALIDATE_ERROR,\n                    \"parameter `serverSpecification.id` is not match uuid pattern,  must obey uuid pattern\");\n            }\n            if (mcpServerIndex.getMcpServerById(serverSpecification.getId()) != null) {\n                throw new NacosApiException(NacosApiException.INVALID_PARAM,\n                    ErrorCode.PARAMETER_VALIDATE_ERROR,\n                    \"parameter `serverSpecification.id` conflict with exist mcp server id\");","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/McpServerOperationService.java#L385-L421","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nMcpServerBasicInfo spec = new McpServerBasicInfo();\nspec.setName(\"my-mcp\");\n// version forgotten\nservice.createMcpServer(ns, spec, ...);\n\n// after\nMcpServerBasicInfo spec = new McpServerBasicInfo();\nspec.setName(\"my-mcp\");\nspec.setVersion(\"1.0.0\");\nservice.createMcpServer(ns, spec, ...);","handlingStrategy":"validation","validationCode":"// Validate version before calling createMcpServer\nif (spec.getVersionDetail() == null && StringUtils.isBlank(spec.getVersion())) {\n    throw new IllegalArgumentException(\"MCP server version is required\");\n}\nservice.createMcpServer(ns, spec, tools, resources, endpoint);","typeGuard":"public static boolean hasValidVersion(McpServerBasicInfo spec) {\n    if (spec.getVersionDetail() != null\n            && StringUtils.isNotBlank(spec.getVersionDetail().getVersion())) {\n        return true;\n    }\n    return StringUtils.isNotBlank(spec.getVersion());\n}","tryCatchPattern":"try {\n    service.createMcpServer(ns, spec, ...);\n} catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()\n            && e.getMessage().contains(\"Version must be specified\")) {\n        spec.setVersion(\"1.0.0\");\n        service.createMcpServer(ns, spec, ...);\n    } else {\n        throw e;\n    }\n}","preventionTips":["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'."],"tags":["mcp-server","validation","version","create","invalid-param"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}