alibaba/nacos · error · IllegalArgumentException

${fieldName} must not be null

Error message

${fieldName} must not be null

What it means

Thrown (as IllegalArgumentException) by the RAD AgentEndpointRegister gRPC handler when the inner `registrationBatch` of AgentEndpointRegisterRpcRequest is null. The requireRequest() guard rejects it; AgentGrpcResponseErrorMapper maps the exception to PARAMETER_VALIDATE_ERROR on the response.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/remote/handler/agent/AgentEndpointRegisterRpcRequestHandler.java:74

    @Secured(action = ActionTypes.WRITE, signType = SignType.AI)
    public AgentEndpointOperationResponse handle(AgentEndpointRegisterRpcRequest request,
        RequestMeta meta) throws NacosException {
        AgentEndpointOperationResponse response = new AgentEndpointOperationResponse();
        try {
            AgentEndpointRegistrationBatch batch =
                requireRequest(request.getRegistrationBatch(), "registrationBatch");
            batch.setNamespaceId(NamespaceUtil.processNamespaceParameter(
                batch.getNamespaceId()));
            runtimeRegistryService.register(meta.getConnectionId(), batch);
        } catch (Exception e) {
            AgentGrpcResponseErrorMapper.apply(response, e);
        }
        return response;
    }
    
    private <T> T requireRequest(T value, String fieldName) {
        if (value == null) {
            throw new IllegalArgumentException(fieldName + " must not be null");
        }
        return value;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set a non-null AgentEndpointRegistrationBatch on the request before sending.
2. Add a client-side precondition: Objects.requireNonNull(request.getRegistrationBatch()).
3. Use a builder that enforces the batch as a required parameter.

Example fix

// before
AgentEndpointRegisterRpcRequest req = new AgentEndpointRegisterRpcRequest();
// registrationBatch never set -> error

// after
req.setRegistrationBatch(buildBatch());

Objects.requireNonNull(request.getRegistrationBatch(), "registrationBatch");

boolean hasBatch(AgentEndpointRegisterRpcRequest r) {
    return r != null && r.getRegistrationBatch() != null;
}

if (response.getErrorCode() != 0) { handle(response.getMessage()); }

When it happens

Trigger: Sending an AgentEndpointRegisterRpcRequest whose getRegistrationBatch() returns null. The handler validates the batch first, then applies namespace processing and delegates to the runtime registry.

Common situations: Client sends the outer envelope without the AgentEndpointRegistrationBatch payload; field name mismatch during serialization; conditional code that skips batch construction.

Related errors

• ${fieldName} must not be null
• publishRequest must not be null
• ${fieldName} must not be null
• 10000
• 20002

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