{"record":{"id":"16bb50086f6b4e4b","repo":"alibaba/nacos","slug":"preferredlatest-must-target-the-created-version","errorCode":null,"errorMessage":"preferredLatest must target the created Version","messagePattern":"preferredLatest must target the created Version","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1077,"sourceCode":"        }\n        if (version.getNamespaceId() != null\n            && !namespaceId.equals(version.getNamespaceId())) {\n            throw new IllegalArgumentException(\"Agent Version namespaceId does not match request\");\n        }\n        if (version.getAgentName() != null && !agentName.equals(version.getAgentName())) {\n            throw new IllegalArgumentException(\"Agent Version agentName does not match request\");\n        }\n        if (version.getStatus() != null\n            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(version.getStatus())) {\n            throw new IllegalArgumentException(\"Agent Version status must be online\");\n        }\n        if (version.getContentDigest() != null || version.getCreateTime() != null\n            || version.getUpdateTime() != null) {\n            throw new IllegalArgumentException(\n                \"Agent Version must not contain read-only projection fields\");\n        }\n        if (preferredLatest != null && !version.getVersion().equals(preferredLatest)) {\n            throw new IllegalArgumentException(\"preferredLatest must target the created Version\");\n        }\n    }\n    \n    private void validateAgentUpdateInputs(Agent replacement) {\n        if (replacement == null) {\n            throw new IllegalArgumentException(\"Agent replacement must not be null\");\n        }\n        AgentValidationUtils.validateNamespaceId(replacement.getNamespaceId());\n        AgentValidationUtils.validateAgentName(replacement.getAgentName());\n        if (replacement.getVersionInfo() != null || replacement.getVersionCatalog() != null\n            || replacement.getMetaVersion() != null || replacement.getCreateTime() != null\n            || replacement.getUpdateTime() != null) {\n            throw new IllegalArgumentException(\n                \"Agent update input must not contain read-only projection fields\");\n        }\n    }\n    \n    private Agent normalizeAgentUpdate(Agent source, Agent current) {","sourceCodeStart":1059,"sourceCodeEnd":1095,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1059-L1095","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass preferredLatest = null to let the server preserve the existing latest pointer.","Pass preferredLatest = version.getVersion() to promote the created Version to latest.","Do not pass any other version string as preferredLatest."],"exampleFix":"// before — preferredLatest targets the wrong version\npersistenceService.createOnlineVersion(ns, name, version, \"other-version\"); // throws\n\n// after — either null or the created version\npersistenceService.createOnlineVersion(ns, name, version, version.getVersion());","handlingStrategy":"validation","validationCode":"if (preferredLatest != null && !version.getVersion().equals(preferredLatest)) {\n    throw new IllegalArgumentException(\"preferredLatest must equal version or be null\");\n}","typeGuard":"boolean preferredLatestConsistent(String version, String preferredLatest) {\n    return preferredLatest == null || version.equals(preferredLatest);\n}","tryCatchPattern":null,"preventionTips":["Use null for preferredLatest unless you explicitly want to set the latest label.","When promoting to latest, always pass version.getVersion() as preferredLatest."],"tags":["agent","ai-registry","validation","preferred-latest","online-version"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}