alibaba/nacos · error · IllegalArgumentException

Agent replacement must not be null

Error message

Agent replacement must not be null

What it means

Thrown by AgentOperationService.updateAgent as an IllegalArgumentException when the replacement parameter is null. This is a programming-error guard — the public API contract requires a non-null Agent object. It is not a NacosApiException; it will surface as a 500 or unchecked-exception propagation depending on the controller's exception handler.

Source

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

    public AgentOverview getOverview(String namespaceId, String agentName) throws NacosException {
        AiResource meta = requireMeta(namespaceId, agentName);
        resourceManager.ensureReadableOrNotFound(meta, "Agent not found: " + agentName);
        return persistenceService.getAgentOverview(namespaceId, agentName,
            OVERVIEW_VERSION_PAGE_SIZE);
    }
    
    /**
     * Replace Agent-level presentation, catalog, and resource-status metadata.
     *
     * <p>This operation does not modify Agent Version content, owner, or scope.</p>
     *
     * @param replacement complete writable Agent replacement
     * @return updated Agent
     * @throws NacosException when the Agent is absent, not writable, or persistence fails
     */
    public Agent updateAgent(Agent replacement) throws NacosException {
        if (replacement == null) {
            throw new IllegalArgumentException("Agent replacement must not be null");
        }
        for (int i = 0; i < AiResourceConstants.MAX_WORKING_VERSION_RETRY; i++) {
            AiResource current =
                requireWritableMeta(replacement.getNamespaceId(), replacement.getAgentName());
            Agent result = persistenceService.tryUpdateAgent(replacement, current);
            if (result != null) {
                AiResourceTraceService.logSuccess(RESOURCE_TYPE, replacement.getAgentName(), null,
                    AiResourceTraceService.OP_UPDATE_RESOURCE,
                    VisibilityHelper.resolveCurrentIdentity(), VisibilityHelper.resolveClientIp());
                return result;
            }
        }
        throw conflict("Agent metadata changed concurrently: " + replacement.getAgentName());
    }
    
    /**
     * Filter and page visible Agent summaries.
     *

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Add a null check before calling updateAgent and return a 400 Bad Request from the controller.
2. Ensure the caller always constructs and populates the Agent object before the call.
3. If deserializing, validate the request body is non-empty and maps to a non-null object.

Example fix

// before
agentOperationService.updateAgent(null);

// after
if (replacement == null) {
    throw new IllegalArgumentException("replacement must not be null");
}
agentOperationService.updateAgent(replacement);

// Null-check at the controller or caller layer
if (replacement == null) {
    throw new IllegalArgumentException("Agent replacement must not be null");
}
agentOperationService.updateAgent(replacement);

public static boolean isValidAgentReplacement(Agent replacement) {
    return replacement != null
        && StringUtils.isNotBlank(replacement.getNamespaceId())
        && StringUtils.isNotBlank(replacement.getAgentName());
}

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

When it happens

Trigger: Calling updateAgent(null) directly. Passing a variable that was not initialized or was set to null by a failed lookup. Deserialization producing null when the request body was empty.

Common situations: Controller receives an empty request body that deserializes to null. Code path where the Agent object is conditionally built and the else branch passes null. Refactoring that accidentally removed the initialization.

Related errors

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

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