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.

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.

Appendix: 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)