alibaba/nacos · error · IllegalArgumentException

preferredLatest must target the created Version

Error message

preferredLatest must target the created Version

What it means

When createOnlineVersion receives a non-null preferredLatest, that value must equal the version string of the Version being created. preferredLatest promotes the created Version to the 'latest' label; targeting a different version would be a logic error.

Source

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

        }
        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
            || replacement.getMetaVersion() != null || replacement.getCreateTime() != null
            || replacement.getUpdateTime() != null) {
            throw new IllegalArgumentException(
                "Agent update input must not contain read-only projection fields");
        }
    }
    
    private Agent normalizeAgentUpdate(Agent source, Agent current) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass preferredLatest = null to let the server preserve the existing latest pointer.
2. Pass preferredLatest = version.getVersion() to promote the created Version to latest.
3. Do not pass any other version string as preferredLatest.

Example fix

// before — preferredLatest targets the wrong version
persistenceService.createOnlineVersion(ns, name, version, "other-version"); // throws

// after — either null or the created version
persistenceService.createOnlineVersion(ns, name, version, version.getVersion());

if (preferredLatest != null && !version.getVersion().equals(preferredLatest)) {
    throw new IllegalArgumentException("preferredLatest must equal version or be null");
}

boolean preferredLatestConsistent(String version, String preferredLatest) {
    return preferredLatest == null || version.equals(preferredLatest);
}

When it happens

Trigger: Calling createOnlineVersion(ns, name, version, preferredLatest) where preferredLatest is non-null and !version.getVersion().equals(preferredLatest). In the normal direct-online flow, preferredLatest is either null or set to request.getVersion(), so this fires only if a caller passes a different version string.

Common situations: A caller passes a hardcoded 'latest' label or a stale version string as preferredLatest. A copy-paste error passes the wrong version identifier for the latest pointer.

Related errors

• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version agentName does not match request
• Agent Version status must be online
• Agent Version must not contain read-only projection fields

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