alibaba/nacos · error · IllegalArgumentException

Agent Version agentName does not match request

Error message

Agent Version agentName does not match request

What it means

When an AgentVersionDetail submitted for online creation carries a non-null agentName, that value must match the agentName argument passed to createOnlineVersion. This ensures the Version is linked to the correct Agent resource and prevents accidental cross-Agent Version creation.

Source

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

    }
    
    private void validateOnlineVersionInputs(String namespaceId, String agentName,
        AgentVersionDetail version, String preferredLatest) {
        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");

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set version.setAgentName(null) before calling createOnlineVersion and let the server assign it.
2. Ensure version.getAgentName() exactly matches the agentName parameter (case-sensitive).
3. Strip server-populated identity fields from Version details before re-submitting.

Example fix

// before — agentName carried over from a different Agent
version.setAgentName("old-agent");
persistenceService.createOnlineVersion(ns, "new-agent", version, null); // throws

// after — let the server assign agentName
version.setAgentName(null);
persistenceService.createOnlineVersion(ns, "new-agent", version, null);

if (version.getAgentName() != null && !agentName.equals(version.getAgentName())) {
    throw new IllegalArgumentException("agentName mismatch: " + agentName);
}

boolean agentNameConsistent(String agentName, AgentVersionDetail v) {
    return v.getAgentName() == null || agentName.equals(v.getAgentName());
}

When it happens

Trigger: Calling createOnlineVersion(namespaceId, agentName, version, preferredLatest) where version.getAgentName() is non-null and differs from the agentName parameter. The toOnlineVersion converter normally leaves agentName null, so this fires only when a caller explicitly sets a mismatched agentName.

Common situations: A client renames an Agent and resubmits a Version detail that still carries the old agentName. A copy-paste error between Agent creation requests puts the wrong agentName inside the version body.

Related errors

• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version status must be online
• 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/d5b3c7e7fd1195ef. Report an issue: GitHub.