alibaba/nacos · error · IllegalArgumentException

Agent direct-online request must not be null

Error message

Agent direct-online request must not be null

What it means

Thrown by AgentOperationService.validateDirectOnlineRequest as an IllegalArgumentException when the direct-online request parameter is null. This is a precondition guard for the direct-online registration path (registering a version that goes straight to ONLINE status without a draft cycle). Unchecked exception, not a NacosApiException.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java:771

            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {
            throw illegalState("Agent Version cannot be restored online from status " + status
                + ": " + agentName + '@' + version);
        }
        persistenceService.updateVersionStatus(namespaceId, agentName, version,
            AiConstants.Agent.VERSION_STATUS_ONLINE);
        persistenceService.synchronizeDerivedState(namespaceId, agentName,
            setAsLatest ? version : null, null,
            AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status) ? version : null,
            AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)
                || AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status) ? version : null);
        return persistenceService.getAgentVersion(namespaceId, agentName, version);
    }
    
    private void validateDirectOnlineRequest(String namespaceId,
        AgentDraftCreateRequest request) {
        if (request == null) {
            throw new IllegalArgumentException("Agent direct-online request must not be null");
        }
        AgentValidationUtils.validateNamespaceId(namespaceId);
        request.validate();
        if (request.getCallInterfaces() == null || StringUtils.isNotBlank(
            request.getBasedOnVersion())) {
            throw new IllegalArgumentException(
                "Agent direct-online request must contain callInterfaces");
        }
    }
    
    private AgentVersionDetail toOnlineVersion(AgentDraftCreateRequest request) {
        AgentVersionDetail result = new AgentVersionDetail();
        result.setVersion(request.getVersion());
        result.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE);
        result.setCallInterfaces(request.getCallInterfaces());
        result.setAuthor(request.getAuthor());
        result.setChangeDescription(request.getChangeDescription());
        return result;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate the request is non-null at the controller before calling the direct-online path.
2. Ensure the client always sends a complete request body for direct-online registration.
3. Return HTTP 400 at the controller layer if the body is missing.

Example fix

// before
service.registerDirectOnline(ns, null);

// after
if (request == null) {
    return ResponseEntity.badRequest().body("direct-online request required");
}
service.registerDirectOnline(ns, request);

// Null-check at the controller before calling direct-online
if (request == null) {
    return ResponseEntity.badRequest().body("direct-online request body is required");
}
agentOperationService.registerDirectOnline(ns, request);

public static boolean isValidDirectOnlineRequest(AgentDraftCreateRequest request) {
    return request != null;
}

try {
    agentOperationService.registerDirectOnline(ns, request);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must not be null")) {
        return ResponseEntity.badRequest().body(e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Calling the direct-online registration path with a null request object. Controller deserialization producing null from an empty body. Code path where the request is conditionally constructed.

Common situations: Empty request body on the direct-online endpoint. JSON parse failure yielding null. Refactoring that removed request construction in a branch.

Related errors

• Agent replacement must not be null
• Agent draft request must not be null
• Agent direct-online request must contain callInterfaces
• 10000
• 20002

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