{"record":{"id":"532e406be84613b0","repo":"alibaba/nacos","slug":"parameter-validate-error-532e40","errorCode":"PARAMETER_VALIDATE_ERROR","errorMessage":"Required parameter `endpoint.version` can't be different, current includes: %s.","messagePattern":"Required parameter `endpoint\\.version` can't be different, current includes: (.+?)\\.","errorType":"validation","errorClass":"NacosApiException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/com/alibaba/nacos/client/ai/NacosAiService.java","lineNumber":402,"sourceCode":"        aiChangeNotifier.deregisterListener(agentName, version, listenerInvoker);\n        if (!aiChangeNotifier.isAgentCardSubscribed(agentName, version)) {\n            grpcClient.unsubscribeAgentCard(agentName, version);\n        }\n    }\n    \n    private void validateAgentEndpoint(Collection<AgentEndpoint> endpoints)\n        throws NacosApiException {\n        if (null == endpoints || endpoints.isEmpty()) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"parameters `endpoints` can't be empty or null, if want to deregister endpoints, please use deregister API.\");\n        }\n        Set<String> versions = new HashSet<>();\n        for (AgentEndpoint endpoint : endpoints) {\n            validateAgentEndpoint(endpoint);\n            versions.add(endpoint.getVersion());\n        }\n        if (versions.size() > 1) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                String.format(\n                    \"Required parameter `endpoint.version` can't be different, current includes: %s.\",\n                    String.join(\",\", versions)));\n        }\n    }\n    \n    private void validateAgentEndpoint(AgentEndpoint endpoint) throws NacosApiException {\n        if (null == endpoint) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"parameters `endpoint` can't be null\");\n        }\n        if (StringUtils.isBlank(endpoint.getVersion())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Required parameter `endpoint.version` can't be empty or null\");\n        }\n        Instance instance = new Instance();\n        instance.setIp(endpoint.getAddress());","sourceCodeStart":384,"sourceCodeEnd":420,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/ai/NacosAiService.java#L384-L420","documentation":"In the batch validator, after every endpoint is individually validated, the distinct `getVersion()` values are collected; if more than one distinct version is present the whole batch is rejected. This is ErrorCode.PARAMETER_VALIDATE_ERROR (detailErrCode 20002), NOT PARAMETER_MISSING — it is a semantic constraint, not a missing field.","triggerScenarios":"Calling registerAgentEndpoint(name, [ep(v=1.0.0), ep(v=1.1.0)]); mixing versions in one batch call.","commonSituations":"Aggregating endpoints from multiple sources/versions into one batch without grouping by version; incrementing a version for some replicas but not others in the same call.","solutions":["Group endpoints by version and make one registerAgentEndpoint call per version.","Ensure every AgentEndpoint.getVersion() in a single batch returns the same string.","Distinguish this (detailErrCode 20002) from a missing-version field error (10000)."],"exampleFix":"// before\nList<AgentEndpoint> mixed = List.of(ep10, ep11); // different versions\naiService.registerAgentEndpoint(agentName, mixed);\n\n// after - one call per version\nMap<String, List<AgentEndpoint>> byVer = mixed.stream()\n    .collect(Collectors.groupingBy(AgentEndpoint::getVersion));\nbyVer.values().forEach(batch -> aiService.registerAgentEndpoint(agentName, batch));","handlingStrategy":"validation","validationCode":"// group by version before batch-registering\nMap<String, List<AgentEndpoint>> byVersion = endpoints.stream()\n    .collect(Collectors.groupingBy(AgentEndpoint::getVersion));\nfor (List<AgentEndpoint> batch : byVersion.values()) {\n    aiService.registerAgentEndpoint(agentName, batch);\n}","typeGuard":null,"tryCatchPattern":"catch (NacosApiException e) {\n    if (e.getDetailErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()) {\n        // mixed versions in batch — split and retry per version\n        LOG.warn(\"Endpoint batch had mixed versions: {}\", e.getMessage());\n        return;\n    }\n    throw e;\n}","preventionTips":["This is detailErrCode 20002 (PARAMETER_VALIDATE_ERROR), distinct from PARAMETER_MISSING 10000.","A single batch must target exactly one agent version."],"tags":["a2a","agent","validation","client-sdk","ai","batch","version","parameter-validate-error"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}