{"record":{"id":"674371e8086c57e5","repo":"alibaba/nacos","slug":"invalid-agent-version-status-status","errorCode":null,"errorMessage":"Invalid Agent Version status: {status}","messagePattern":"Invalid Agent Version status: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":354,"sourceCode":"        if (!\"PUBLIC\".equals(scope) && !\"PRIVATE\".equals(scope)) {\n            throw new IllegalArgumentException(\"scope must be PUBLIC or PRIVATE\");\n        }\n    }\n    \n    private static void validateResourceStatus(String status) {\n        if (!AiConstants.Agent.RESOURCE_STATUS_ENABLE.equals(status)\n            && !AiConstants.Agent.RESOURCE_STATUS_DISABLE.equals(status)) {\n            throw new IllegalArgumentException(\"Invalid Agent resource status: \" + status);\n        }\n    }\n    \n    private static void validateVersionStatus(String status) {\n        if (!AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {\n            throw new IllegalArgumentException(\"Invalid Agent Version status: \" + status);\n        }\n    }\n    \n    private static void validateTags(List<String> tags) {\n        if (tags == null) {\n            return;\n        }\n        if (tags.size() > MAX_TAGS) {\n            throw new IllegalArgumentException(\"tags exceeds \" + MAX_TAGS + \" items\");\n        }\n        Set<String> uniqueTags = new HashSet<String>();\n        for (String tag : tags) {\n            validateRequiredLength(tag, MAX_TAG_LENGTH, \"tag\");\n            if (!uniqueTags.add(tag)) {\n                throw new IllegalArgumentException(\"Duplicate tag: \" + tag);\n            }\n        }\n    }","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L336-L372","documentation":"Thrown by AgentModelValidator.validateVersionStatus when an Agent Version's status is not one of the five allowed lifecycle values. The Agent Version lifecycle is an enum-like string contract: draft, reviewing, reviewed, online, offline. Any other string (including typos, uppercase variants, or null passed through string concat) is rejected because the server state machine cannot transition to an unknown status.","triggerScenarios":"Calling validateVersionSummary or validateVersionDetail with a Version whose status field is e.g. \"enabled\", \"PUBLISHED\", \"on\", \"\", or a localized string. Also triggered when a client SDK serializes a status enum as its name() but the server expects lowercase constants.","commonSituations":"Migrating from an older Nacos AI registry that accepted free-form status strings; integrating a non-Java client that sends uppercase enum names; copy-pasting an Agent resource status (enable/disable) into a Version status field, since resource status and version status are different vocabularies.","solutions":["Set the Version status to one of the exact lowercase constants: draft, reviewing, reviewed, online, or offline.","If you build the value from an enum, map it with AiConstants.Agent.VERSION_STATUS_* rather than enum.name().toLowerCase().","Do not reuse Agent resource status values (enable/disable) for Version status.","Grep your client code for any place that constructs a Version status dynamically and harden it against unknown inputs."],"exampleFix":"// before\nversionSummary.setStatus(\"enabled\");\n// after\nversionSummary.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE); // \"online\"","handlingStrategy":"validation","validationCode":"private static final Set<String> VERSION_STATUSES = Set.of(\n    AiConstants.Agent.VERSION_STATUS_DRAFT,\n    AiConstants.Agent.VERSION_STATUS_REVIEWING,\n    AiConstants.Agent.VERSION_STATUS_REVIEWED,\n    AiConstants.Agent.VERSION_STATUS_ONLINE,\n    AiConstants.Agent.VERSION_STATUS_OFFLINE);\n\nstatic String checkVersionStatus(String status) {\n    if (!VERSION_STATUSES.contains(status)) {\n        throw new IllegalArgumentException(\"Unknown Version status: \" + status);\n    }\n    return status;\n}","typeGuard":"static boolean isValidVersionStatus(String s) {\n    return s != null && Set.of(\"draft\", \"reviewing\", \"reviewed\", \"online\", \"offline\").contains(s);\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateVersionSummary(summary);\n} catch (IllegalArgumentException e) {\n    // log and surface a 400 to the client with the validator's message\n}","preventionTips":["Always source Version status from AiConstants.Agent.VERSION_STATUS_* constants, never from user input or enum.name().","Validate status at the API boundary before constructing the model object.","Keep resource status (enable/disable) and Version status vocabularies in separate code paths."],"tags":["ai-agent","validation","status-lifecycle","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}