alibaba/nacos · error · IllegalArgumentException

Agent Version namespaceId does not match request

Error message

Agent Version namespaceId does not match request

What it means

When an AgentVersionDetail submitted for online creation carries a non-null namespaceId, that value must match the namespaceId argument passed to createOnlineVersion. This prevents cross-namespace data leakage by ensuring the Version is authored into the namespace the caller is authorized for.

Source

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

            && !expectedStatus.equals(initialVersion.getStatus())) {
            throw new IllegalArgumentException("initialVersion status must be " + expectedStatus);
        }
    }
    
    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");
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Set version.setNamespaceId(null) before calling createOnlineVersion and let the server assign it.
Ensure version.getNamespaceId() equals the namespaceId parameter exactly (case-sensitive).
Do not reuse a Version detail read from a GET response without clearing server-populated fields.

Example fix

// before — namespaceId carried over from a different context
version.setNamespaceId("staging");
persistenceService.createOnlineVersion("public", name, version, null); // throws

// after — let the server assign namespaceId
version.setNamespaceId(null);
persistenceService.createOnlineVersion("public", name, version, null);

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean namespaceConsistent(String ns, AgentVersionDetail v) {
    return v.getNamespaceId() == null || ns.equals(v.getNamespaceId());
}

Prevention

Never reuse a Version detail from a GET response for a create call without clearing namespaceId.
Let the server assign namespaceId — leave it null on write payloads.
Treat namespaceId as a path/resource-identity field, not a writable body field.

When it happens

Trigger: Calling createOnlineVersion(namespaceId, agentName, version, preferredLatest) where version.getNamespaceId() is non-null and differs from the namespaceId parameter. The toOnlineVersion converter normally leaves namespaceId null (server fills it), so this fires only if a caller explicitly sets a mismatched namespaceId on the Version detail.

Common situations: A client copies a Version detail from one namespace and re-submits it in another without clearing namespaceId. A migration or import tool preserves the source namespaceId instead of letting the server assign it.

Related errors

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