{"record":{"id":"fdd5a29fba0afd32","repo":"alibaba/nacos","slug":"onlinecnt-must-be-a-non-negative-integer","errorCode":null,"errorMessage":"onlineCnt must be a non-negative integer","messagePattern":"onlineCnt must be a non-negative integer","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":397,"sourceCode":"            throw new IllegalArgumentException(\n                \"extensions exceeds \" + MAX_EXTENSIONS + \" entries\");\n        }\n        for (String key : extensions.keySet()) {\n            validateRequiredLength(key, MAX_EXTENSION_KEY_LENGTH, \"extension key\");\n        }\n    }\n    \n    private static void validateVersionInfo(AgentVersionInfo versionInfo) {\n        requireNonNull(versionInfo, \"versionInfo\");\n        if (versionInfo.getEditingVersion() != null) {\n            AgentValidationUtils.validateVersion(versionInfo.getEditingVersion());\n        }\n        if (versionInfo.getReviewingVersion() != null) {\n            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();","sourceCodeStart":379,"sourceCodeEnd":415,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L379-L415","documentation":"Thrown by validateVersionInfo when AgentVersionInfo.onlineCnt is null or negative. onlineCnt is the cached count of currently-online Versions for the Agent and must be a non-negative integer. It is a denormalized field that the catalog-consistency check (error 485) will subsequently require to equal onlineVersions.size().","triggerScenarios":"Constructing an AgentVersionInfo with onlineCnt left null (default), set to -1, or computed from a query that returned no rows and was assigned a sentinel value.","commonSituations":"Building the versionInfo client-side for a create operation where there are no online versions yet but the field was omitted rather than set to 0; deserializing a malformed payload where the count arrived as null.","solutions":["Set onlineCnt to a non-negative integer, ideally the exact size of the online Versions list.","For a fresh Agent with no online Versions, set onlineCnt = 0 explicitly.","If you compute it from a query, default the empty result to 0 rather than null."],"exampleFix":"// before\nversionInfo.setOnlineCnt(null);\n// after\nversionInfo.setOnlineCnt(0);","handlingStrategy":"validation","validationCode":"static int normalizeOnlineCnt(Integer raw) {\n    if (raw == null || raw < 0) {\n        throw new IllegalArgumentException(\"onlineCnt must be a non-negative integer\");\n    }\n    return raw;\n}","typeGuard":"static boolean isValidOnlineCnt(Integer c) {\n    return c != null && c >= 0;\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"onlineCnt must be a non-negative\")) {\n        agent.getVersionInfo().setOnlineCnt(0);\n    }\n}","preventionTips":["Always set onlineCnt explicitly, even to 0 for fresh Agents.","Never use null or negative sentinels for counts.","Derive onlineCnt from the online Versions list rather than caching it."],"tags":["ai-agent","validation","version-info","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}