alibaba/nacos · error · IllegalArgumentException

Agent Version status must be online

Error message

Agent Version status must be online

What it means

An AgentVersionDetail submitted via createOnlineVersion may optionally carry a status, but if present it must be 'online' (AiConstants.Agent.VERSION_STATUS_ONLINE). This guard rejects Versions that arrive with a contradictory status such as 'draft' or 'offline' on the direct-online creation path.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java:1069

        AgentValidationUtils.validateNamespaceId(namespaceId);
        AgentValidationUtils.validateAgentName(agentName);
        if (version == null) {
            throw new IllegalArgumentException("Agent Version must not be null");
        }
        AgentValidationUtils.validateVersion(version.getVersion());
        if (version.getCallInterfaces() == null) {
            throw new IllegalArgumentException("Online Agent Version must contain callInterfaces");
        }
        if (version.getNamespaceId() != null
            && !namespaceId.equals(version.getNamespaceId())) {
            throw new IllegalArgumentException("Agent Version namespaceId does not match request");
        }
        if (version.getAgentName() != null && !agentName.equals(version.getAgentName())) {
            throw new IllegalArgumentException("Agent Version agentName does not match request");
        }
        if (version.getStatus() != null
            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(version.getStatus())) {
            throw new IllegalArgumentException("Agent Version status must be online");
        }
        if (version.getContentDigest() != null || version.getCreateTime() != null
            || version.getUpdateTime() != null) {
            throw new IllegalArgumentException(
                "Agent Version must not contain read-only projection fields");
        }
        if (preferredLatest != null && !version.getVersion().equals(preferredLatest)) {
            throw new IllegalArgumentException("preferredLatest must target the created Version");
        }
    }
    
    private void validateAgentUpdateInputs(Agent replacement) {
        if (replacement == null) {
            throw new IllegalArgumentException("Agent replacement must not be null");
        }
        AgentValidationUtils.validateNamespaceId(replacement.getNamespaceId());
        AgentValidationUtils.validateAgentName(replacement.getAgentName());
        if (replacement.getVersionInfo() != null || replacement.getVersionCatalog() != null

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set version.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE) before calling createOnlineVersion.
2. Set version.setStatus(null) to let the server assign 'online' status.
3. Use the toOnlineVersion(request) factory rather than constructing AgentVersionDetail manually.

Example fix

// before — draft status on an online path
version.setStatus(AiConstants.Agent.VERSION_STATUS_DRAFT);
persistenceService.createOnlineVersion(ns, name, version, null); // throws

// after — correct status or omit it
version.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE);
persistenceService.createOnlineVersion(ns, name, version, null);

if (version.getStatus() != null && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(version.getStatus())) {
    throw new IllegalArgumentException("status must be online or null, got: " + version.getStatus());
}

boolean statusValidForOnline(AgentVersionDetail v) {
    return v.getStatus() == null || AiConstants.Agent.VERSION_STATUS_ONLINE.equals(v.getStatus());
}

When it happens

Trigger: Calling createOnlineVersion with an AgentVersionDetail whose getStatus() returns a non-null value other than 'online'. The toOnlineVersion converter always sets status to VERSION_STATUS_ONLINE, so this fires only when a caller overrides the status after conversion or constructs the detail manually.

Common situations: A caller copies a draft Version detail (status='draft') and passes it to the online path instead of the draft path. A generic Version factory defaults status to 'draft' and is reused for both paths.

Related errors

• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version agentName does not match request
• Agent Version must not contain read-only projection fields
• preferredLatest must target the created Version

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