{"record":{"id":"37ce2010548afacb","repo":"alibaba/nacos","slug":"invalid-param-37ce20","errorCode":"INVALID_PARAM","errorMessage":"Required parameter `agentName` can't be empty or null","messagePattern":"Required parameter `agentName` can't be empty or null","errorType":"exception","errorClass":"NacosApiException","httpStatus":400,"severity":"warning","filePath":"ai/src/main/java/com/alibaba/nacos/ai/remote/handler/a2a/BatchAgentEndpointRequestHandler.java","lineNumber":127,"sourceCode":"            String serviceName = agentIdCodecHolder.encode(request.getAgentName()) + \"::\" + version;\n            Service service =\n                Service.newService(request.getNamespaceId(), Constants.Agent.AGENT_ENDPOINT_GROUP,\n                    serviceName);\n            clientOperationService.batchRegisterInstance(service, instances,\n                meta.getConnectionId());\n            publishBatchRegisterInstanceTraceEvent(service, instances, meta);\n        } catch (NacosApiException e) {\n            response.setErrorInfo(e.getErrCode(), e.getErrMsg());\n            LOGGER.error(\"[{}] Batch Register agent endpoints to agent {} error: {}\",\n                meta.getConnectionId(),\n                request.getAgentName(), e.getErrMsg());\n        }\n        return response;\n    }\n    \n    private void validateRequest(BatchAgentEndpointRequest request) throws NacosApiException {\n        if (StringUtils.isBlank(request.getAgentName())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Required parameter `agentName` can't be empty or null\");\n        }\n        if (null == request.getEndpoints() || request.getEndpoints().isEmpty()) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Required parameter `endpoints` can't be empty or null, if want to deregister, please use deregister API.\");\n        }\n        Collection<AgentEndpoint> endpoints = request.getEndpoints();\n        Set<String> versions = new HashSet<>();\n        for (AgentEndpoint each : endpoints) {\n            if (StringUtils.isBlank(each.getVersion())) {\n                throw new NacosApiException(NacosException.INVALID_PARAM,\n                    ErrorCode.PARAMETER_MISSING,\n                    \"Required parameter `endpoint.version` can't be empty or null.\");\n            }\n            versions.add(each.getVersion());\n        }\n        if (versions.size() > 1) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/remote/handler/a2a/BatchAgentEndpointRequestHandler.java#L109-L145","documentation":"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.","triggerScenarios":"A gRPC BatchAgentEndpointRequest (batch register endpoints, since 3.1.1) with agentName null/empty/whitespace.","commonSituations":"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.","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)."],"exampleFix":"// before\nBatchAgentEndpointRequest req = new BatchAgentEndpointRequest();\nreq.setEndpoints(List.of(ep));\n// agentName not set\n\n// after\nreq.setAgentName(\"my-a2a-agent\");\nreq.setEndpoints(List.of(ep));","handlingStrategy":"validation","validationCode":"if (StringUtils.isBlank(request.getAgentName())) {\n    throw new IllegalArgumentException(\"BatchAgentEndpointRequest.agentName must not be blank\");\n}","typeGuard":"static boolean hasAgentName(BatchAgentEndpointRequest r) {\n    return r != null && !StringUtils.isBlank(r.getAgentName());\n}","tryCatchPattern":"AgentEndpointResponse resp = handler.handle(request, meta);\nif (resp.getErrCode() != 0 && resp.getErrMsg().contains(\"agentName\")) {\n    // set agentName and retry the batch\n}","preventionTips":["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."],"tags":["ai","a2a-agent","grpc","validation","parameter","batch","endpoint"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}