{"record":{"id":"72cf7d66ca8f186f","repo":"alibaba/nacos","slug":"onlinecnt-must-equal-the-number-of-onlineversions","errorCode":null,"errorMessage":"onlineCnt must equal the number of onlineVersions entries","messagePattern":"onlineCnt must equal the number of onlineVersions entries","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":411,"sourceCode":"            AgentValidationUtils.validateVersion(versionInfo.getReviewingVersion());\n        }\n        Integer onlineCount = versionInfo.getOnlineCnt();\n        if (onlineCount == null || onlineCount < 0) {\n            throw new IllegalArgumentException(\"onlineCnt must be a non-negative integer\");\n        }\n        Map<String, String> labels = versionInfo.getLabels();\n        requireNonNull(labels, \"versionInfo.labels\");\n        for (Map.Entry<String, String> entry : labels.entrySet()) {\n            AgentValidationUtils.validateLabel(entry.getKey());\n            AgentValidationUtils.validateVersion(entry.getValue());\n        }\n    }\n    \n    private static void validateVersionInfoCatalogConsistency(AgentVersionInfo versionInfo,\n        AgentVersionCatalog catalog) {\n        List<AgentVersionCatalogEntry> onlineVersions = catalog.getOnlineVersions();\n        if (versionInfo.getOnlineCnt() != onlineVersions.size()) {\n            throw new IllegalArgumentException(\n                \"onlineCnt must equal the number of onlineVersions entries\");\n        }\n        String editingVersion = versionInfo.getEditingVersion();\n        String reviewingVersion = versionInfo.getReviewingVersion();\n        if (editingVersion != null && editingVersion.equals(reviewingVersion)) {\n            throw new IllegalArgumentException(\n                \"editingVersion and reviewingVersion must identify different Versions\");\n        }\n        Set<String> onlineVersionValues = new HashSet<String>();\n        for (AgentVersionCatalogEntry entry : onlineVersions) {\n            onlineVersionValues.add(entry.getVersion());\n        }\n        if (onlineVersionValues.contains(editingVersion)\n            || onlineVersionValues.contains(reviewingVersion)) {\n            throw new IllegalArgumentException(\n                \"editingVersion and reviewingVersion must not identify online Versions\");\n        }\n        for (Map.Entry<String, String> label : versionInfo.getLabels().entrySet()) {","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L393-L429","documentation":"Thrown by validateVersionInfoCatalogConsistency when AgentVersionInfo.onlineCnt does not equal versionCatalog.onlineVersions.size(). These two fields are redundant by design and must agree; a mismatch indicates a torn read or an incorrectly hand-assembled payload. This runs after the non-negativity check (error 484).","triggerScenarios":"Submitting a payload where onlineCnt was cached/stale while the onlineVersions list was edited; setting onlineCnt by hand without recounting; reading onlineVersions from one store and onlineCnt from another in a race.","commonSituations":"Hand-building an Agent model for testing or migration and forgetting to keep the count in sync; a client that caches onlineCnt but recomputes the list.","solutions":["Set onlineCnt = versionCatalog.getOnlineVersions().size() right before validation/submission.","Never cache onlineCnt separately from the list; always derive it.","If loading from storage, recompute the count in the same transaction as the list."],"exampleFix":"// before\nversionInfo.setOnlineCnt(2); catalog.setOnlineVersions(List.of(entry1, entry2, entry3));\n// after\nversionInfo.setOnlineCnt(catalog.getOnlineVersions().size());","handlingStrategy":"validation","validationCode":"static void syncOnlineCnt(AgentVersionInfo info, AgentVersionCatalog catalog) {\n    info.setOnlineCnt(catalog.getOnlineVersions().size());\n}","typeGuard":"static boolean onlineCntMatches(AgentVersionInfo info, AgentVersionCatalog catalog) {\n    return info.getOnlineCnt() != null\n        && info.getOnlineCnt() == catalog.getOnlineVersions().size();\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"onlineCnt must equal\")) {\n        agent.getVersionInfo().setOnlineCnt(\n            agent.getVersionCatalog().getOnlineVersions().size());\n    }\n}","preventionTips":["Set onlineCnt = onlineVersions.size() in the same mutation that changes the list.","Never cache onlineCnt separately from the list.","Load both fields from the same transaction to avoid torn reads."],"tags":["ai-agent","validation","version-info","consistency","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}