alibaba/nacos · error · IllegalArgumentException

Agent draft request must not be null

Error message

Agent draft request must not be null

What it means

Thrown by AgentOperationService.createDraft as an IllegalArgumentException when the request parameter is null. Similar to error 115, this is a precondition guard on the public API. The method signature declares throws NacosException, but this specific null-check throws an unchecked IllegalArgumentException.

Source

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

        return persistenceService.listAgentVersions(namespaceId, agentName, status, pageNo,
            pageSize);
    }
    
    /**
     * Create a new Agent draft Version, creating Agent metadata when it does not exist.
     *
     * <p>An equivalent request may be retried idempotently, but this operation never replaces
     * existing draft content.</p>
     *
     * @param namespaceId namespace identifier
     * @param request draft request
     * @return verified draft detail
     * @throws NacosException when creation fails
     */
    public AgentVersionDetail createDraft(String namespaceId, AgentDraftCreateRequest request)
        throws NacosException {
        if (request == null) {
            throw new IllegalArgumentException("Agent draft request must not be null");
        }
        AgentValidationUtils.validateNamespaceId(namespaceId);
        request.validate();
        String agentName = request.getAgentName();
        AgentVersionDetail draft = toDraft(request);
        AiResource meta = resourceManager.findMeta(namespaceId, agentName, RESOURCE_TYPE);
        AgentVersionDetail result;
        if (meta == null) {
            requireInitialDraftContent(request);
            result = persistenceService.createInitialDraft(toInitialAgent(namespaceId, request),
                draft);
        } else {
            VisibilityHelper.checkWritableResource(meta);
            if (hasInitialAgentMetadata(request)) {
                requireInitialDraftContent(request);
                if (!request.getVersion().equals(
                    AiResourceManager.requireVersionInfo(meta).getEditingVersion())) {
                    throw new IllegalArgumentException(

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate the request is non-null at the controller layer before calling createDraft.
2. Ensure the API client always sends a well-formed request body.
3. Return HTTP 400 from the controller if the body is missing rather than letting the service throw.

Example fix

// before
agentOperationService.createDraft(ns, null);

// after
if (request == null) {
    return ResponseEntity.badRequest().body("request body required");
}
agentOperationService.createDraft(ns, request);

// Null-check at the controller or caller layer
if (request == null) {
    return ResponseEntity.badRequest().body("draft request body is required");
}
agentOperationService.createDraft(namespaceId, request);

public static boolean isValidDraftRequest(AgentDraftCreateRequest request) {
    return request != null && StringUtils.isNotBlank(request.getAgentName());
}

try {
    agentOperationService.createDraft(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 createDraft(namespaceId, null). Controller deserialization yields null for an empty/malformed request body. Code path where the AgentDraftCreateRequest is conditionally built.

Common situations: Empty POST body on the draft-create endpoint. JSON parse error swallowed, producing null. Refactoring that removed request construction in an edge-case branch.

Related errors

• Agent replacement must not be null
• Agent direct-online request must not be null
• Agent directory metadata is only allowed when creating the f
• 10000
• 20002

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