alibaba/nacos · error · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

Required parameter `endpoint.version` can't be different, current includes: %s.

What it means

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.

Source

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

        aiChangeNotifier.deregisterListener(agentName, version, listenerInvoker);
        if (!aiChangeNotifier.isAgentCardSubscribed(agentName, version)) {
            grpcClient.unsubscribeAgentCard(agentName, version);
        }
    }
    
    private void validateAgentEndpoint(Collection<AgentEndpoint> endpoints)
        throws NacosApiException {
        if (null == endpoints || endpoints.isEmpty()) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `endpoints` can't be empty or null, if want to deregister endpoints, please use deregister API.");
        }
        Set<String> versions = new HashSet<>();
        for (AgentEndpoint endpoint : endpoints) {
            validateAgentEndpoint(endpoint);
            versions.add(endpoint.getVersion());
        }
        if (versions.size() > 1) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                String.format(
                    "Required parameter `endpoint.version` can't be different, current includes: %s.",
                    String.join(",", versions)));
        }
    }
    
    private void validateAgentEndpoint(AgentEndpoint endpoint) throws NacosApiException {
        if (null == endpoint) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `endpoint` can't be null");
        }
        if (StringUtils.isBlank(endpoint.getVersion())) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter `endpoint.version` can't be empty or null");
        }
        Instance instance = new Instance();
        instance.setIp(endpoint.getAddress());

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Group endpoints by version and make one registerAgentEndpoint call per version.
  2. Ensure every AgentEndpoint.getVersion() in a single batch returns the same string.
  3. Distinguish this (detailErrCode 20002) from a missing-version field error (10000).

Example fix

// before
List<AgentEndpoint> mixed = List.of(ep10, ep11); // different versions
aiService.registerAgentEndpoint(agentName, mixed);

// after - one call per version
Map<String, List<AgentEndpoint>> byVer = mixed.stream()
    .collect(Collectors.groupingBy(AgentEndpoint::getVersion));
byVer.values().forEach(batch -> aiService.registerAgentEndpoint(agentName, batch));
Defensive patterns

Strategy: validation

Validate before calling

// group by version before batch-registering
Map<String, List<AgentEndpoint>> byVersion = endpoints.stream()
    .collect(Collectors.groupingBy(AgentEndpoint::getVersion));
for (List<AgentEndpoint> batch : byVersion.values()) {
    aiService.registerAgentEndpoint(agentName, batch);
}

Try / catch

catch (NacosApiException e) {
    if (e.getDetailErrCode() == ErrorCode.PARAMETER_VALIDATE_ERROR.getCode()) {
        // mixed versions in batch — split and retry per version
        LOG.warn("Endpoint batch had mixed versions: {}", e.getMessage());
        return;
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling registerAgentEndpoint(name, [ep(v=1.0.0), ep(v=1.1.0)]); mixing versions in one batch call.

Common situations: 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.

Related errors

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