{"record":{"id":"080f525e15c19b5a","repo":"alibaba/nacos","slug":"agent-version-status-must-be-online","errorCode":null,"errorMessage":"Agent Version status must be online","messagePattern":"Agent Version status must be online","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java","lineNumber":1069,"sourceCode":"        AgentValidationUtils.validateNamespaceId(namespaceId);\n        AgentValidationUtils.validateAgentName(agentName);\n        if (version == null) {\n            throw new IllegalArgumentException(\"Agent Version must not be null\");\n        }\n        AgentValidationUtils.validateVersion(version.getVersion());\n        if (version.getCallInterfaces() == null) {\n            throw new IllegalArgumentException(\"Online Agent Version must contain callInterfaces\");\n        }\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","sourceCodeStart":1051,"sourceCodeEnd":1087,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentPersistenceService.java#L1051-L1087","documentation":"An AgentVersionDetail submitted via createOnlineVersion may optionally carry a status, but if present it must be 'online' (AiConstants.Agent.VERSION_STATUS_ONLINE). This guard rejects Versions that arrive with a contradictory status such as 'draft' or 'offline' on the direct-online creation path.","triggerScenarios":"Calling createOnlineVersion with an AgentVersionDetail whose getStatus() returns a non-null value other than 'online'. The toOnlineVersion converter always sets status to VERSION_STATUS_ONLINE, so this fires only when a caller overrides the status after conversion or constructs the detail manually.","commonSituations":"A caller copies a draft Version detail (status='draft') and passes it to the online path instead of the draft path. A generic Version factory defaults status to 'draft' and is reused for both paths.","solutions":["Set version.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE) before calling createOnlineVersion.","Set version.setStatus(null) to let the server assign 'online' status.","Use the toOnlineVersion(request) factory rather than constructing AgentVersionDetail manually."],"exampleFix":"// before — draft status on an online path\nversion.setStatus(AiConstants.Agent.VERSION_STATUS_DRAFT);\npersistenceService.createOnlineVersion(ns, name, version, null); // throws\n\n// after — correct status or omit it\nversion.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE);\npersistenceService.createOnlineVersion(ns, name, version, null);","handlingStrategy":"validation","validationCode":"if (version.getStatus() != null && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(version.getStatus())) {\n    throw new IllegalArgumentException(\"status must be online or null, got: \" + version.getStatus());\n}","typeGuard":"boolean statusValidForOnline(AgentVersionDetail v) {\n    return v.getStatus() == null || AiConstants.Agent.VERSION_STATUS_ONLINE.equals(v.getStatus());\n}","tryCatchPattern":null,"preventionTips":["Use toOnlineVersion(request) to build the detail — it sets status correctly.","Never pass a draft-status Version detail to the online creation path."],"tags":["agent","ai-registry","validation","version-status","online-version"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}