{"record":{"id":"c06479657a651799","repo":"alibaba/nacos","slug":"latestversion-must-be-absent-when-onlineversions-i","errorCode":null,"errorMessage":"latestVersion must be absent when onlineVersions is empty","messagePattern":"latestVersion must be absent when onlineVersions is empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":245,"sourceCode":"     * @throws IllegalArgumentException when the CallInterface is invalid\n     */\n    public static void validateCallInterface(AgentCallInterface callInterface) {\n        validateCallInterface(\"validation\", \"validation\", callInterface);\n    }\n    \n    /**\n     * Validate the compact catalog of online Agent Versions.\n     *\n     * @param catalog Agent Version catalog\n     * @throws IllegalArgumentException when the catalog is invalid\n     */\n    public static void validateVersionCatalog(AgentVersionCatalog catalog) {\n        requireNonNull(catalog, \"versionCatalog\");\n        List<AgentVersionCatalogEntry> versions = catalog.getOnlineVersions();\n        requireNonNull(versions, \"versionCatalog.onlineVersions\");\n        if (versions.isEmpty()) {\n            if (catalog.getLatestVersion() != null) {\n                throw new IllegalArgumentException(\n                    \"latestVersion must be absent when onlineVersions is empty\");\n            }\n            return;\n        }\n        \n        AgentValidationUtils.validateVersion(catalog.getLatestVersion());\n        Set<String> versionValues = new HashSet<String>();\n        Set<String> labelValues = new HashSet<String>();\n        boolean latestFound = false;\n        for (AgentVersionCatalogEntry entry : versions) {\n            requireNonNull(entry, \"versionCatalog entry\");\n            AgentVersion version = AgentVersion.parse(entry.getVersion());\n            if (!versionValues.add(version.getValue())) {\n                throw new IllegalArgumentException(\n                    \"Duplicate online Agent Version: \" + version.getValue());\n            }\n            latestFound |= catalog.getLatestVersion().equals(version.getValue());\n            validateCatalogLabels(entry.getLabels(), labelValues);","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L227-L263","documentation":"Thrown by AgentModelValidator.validateVersionCatalog as an IllegalArgumentException when the catalog's onlineVersions list is empty but latestVersion is non-null. An empty catalog cannot have a 'latest' version, so the two fields are mutually exclusive in that state.","triggerScenarios":"Calling validateVersionCatalog with a catalog where getOnlineVersions() is empty AND getLatestVersion() != null.","commonSituations":"All versions were taken offline but latestVersion was not cleared; a newly-created agent has no online versions yet but a stale latestVersion pointer; a serialization default left latestVersion set.","solutions":["Set catalog.setLatestVersion(null) whenever onlineVersions is empty.","When taking the last version offline, clear latestVersion in the same update.","Build the catalog so latestVersion is derived from onlineVersions rather than set independently."],"exampleFix":"// before\nAgentVersionCatalog catalog = new AgentVersionCatalog();\ncatalog.setOnlineVersions(Collections.emptyList());\ncatalog.setLatestVersion(\"1.0.0\");\nAgentModelValidator.validateVersionCatalog(catalog); // throws\n\n// after\nAgentVersionCatalog catalog = new AgentVersionCatalog();\ncatalog.setOnlineVersions(Collections.emptyList());\ncatalog.setLatestVersion(null);\nAgentModelValidator.validateVersionCatalog(catalog); // ok","handlingStrategy":"validation","validationCode":"if (catalog.getOnlineVersions() == null || catalog.getOnlineVersions().isEmpty()) {\n    catalog.setLatestVersion(null);\n}\nAgentModelValidator.validateVersionCatalog(catalog);","typeGuard":"static boolean catalogIsEmptyConsistent(AgentVersionCatalog catalog) {\n    boolean empty = catalog.getOnlineVersions() == null || catalog.getOnlineVersions().isEmpty();\n    return !empty || catalog.getLatestVersion() == null;\n}","tryCatchPattern":null,"preventionTips":["Clear latestVersion atomically when the last online version is removed.","Derive latestVersion from onlineVersions rather than maintaining it independently.","Treat the empty-catalog + non-null-latest state as a data bug to fix at the source."],"tags":["java","nacos","ai","agents","validation","catalog"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}