alibaba/nacos · warning · NacosApiException

INVALID_PARAM

INVALID_PARAM

Error message

Required parameter `agentName` can't be empty or null

What it means

Thrown by BatchAgentEndpointRequestHandler.validateRequest() when request.getAgentName() is blank. This is the batch-register equivalent of the single-agent check, validated first before the endpoints collection and per-endpoint version checks. Mapped to PARAMETER_MISSING detail code under an INVALID_PARAM top-level code; caught and placed into the AgentEndpointResponse error info. Available since 3.1.1.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/remote/handler/a2a/BatchAgentEndpointRequestHandler.java:127

            String serviceName = agentIdCodecHolder.encode(request.getAgentName()) + "::" + version;
            Service service =
                Service.newService(request.getNamespaceId(), Constants.Agent.AGENT_ENDPOINT_GROUP,
                    serviceName);
            clientOperationService.batchRegisterInstance(service, instances,
                meta.getConnectionId());
            publishBatchRegisterInstanceTraceEvent(service, instances, meta);
        } catch (NacosApiException e) {
            response.setErrorInfo(e.getErrCode(), e.getErrMsg());
            LOGGER.error("[{}] Batch Register agent endpoints to agent {} error: {}",
                meta.getConnectionId(),
                request.getAgentName(), e.getErrMsg());
        }
        return response;
    }
    
    private void validateRequest(BatchAgentEndpointRequest request) throws NacosApiException {
        if (StringUtils.isBlank(request.getAgentName())) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter `agentName` can't be empty or null");
        }
        if (null == request.getEndpoints() || request.getEndpoints().isEmpty()) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter `endpoints` can't be empty or null, if want to deregister, please use deregister API.");
        }
        Collection<AgentEndpoint> endpoints = request.getEndpoints();
        Set<String> versions = new HashSet<>();
        for (AgentEndpoint each : endpoints) {
            if (StringUtils.isBlank(each.getVersion())) {
                throw new NacosApiException(NacosException.INVALID_PARAM,
                    ErrorCode.PARAMETER_MISSING,
                    "Required parameter `endpoint.version` can't be empty or null.");
            }
            versions.add(each.getVersion());
        }
        if (versions.size() > 1) {
            throw new NacosApiException(NacosException.INVALID_PARAM,

View on GitHub (pinned to 9b989acdf1)

Solutions

Set request.setAgentName to the target A2A agent's name before sending the batch.
Validate the agent name is non-blank client-side.
Inspect the AgentEndpointResponse error info after the call to surface the message (no exception is thrown to the caller).

Example fix

// before
BatchAgentEndpointRequest req = new BatchAgentEndpointRequest();
req.setEndpoints(List.of(ep));
// agentName not set

// after
req.setAgentName("my-a2a-agent");
req.setEndpoints(List.of(ep));

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(request.getAgentName())) {
    throw new IllegalArgumentException("BatchAgentEndpointRequest.agentName must not be blank");
}

Type guard

static boolean hasAgentName(BatchAgentEndpointRequest r) {
    return r != null && !StringUtils.isBlank(r.getAgentName());
}

Try / catch

AgentEndpointResponse resp = handler.handle(request, meta);
if (resp.getErrCode() != 0 && resp.getErrMsg().contains("agentName")) {
    // set agentName and retry the batch
}

Prevention

Set agentName from a non-optional config source before batching.
Inspect the AgentEndpointResponse error info; the batch handler places errors there, not in thrown exceptions.
Use the single AgentEndpointRequest validation helper to pre-check batch payloads too.

When it happens

Trigger: A gRPC BatchAgentEndpointRequest (batch register endpoints, since 3.1.1) with agentName null/empty/whitespace.

Common situations: Client builds the batch request from config that omitted the agent name; SDK upgrade where the field moved; a test sending a minimal batch; the agent name sourced from a registry entry not yet created.

Related errors

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