{"record":{"id":"0fb9ce1a01f66b4a","repo":"alibaba/nacos","slug":"latestversion-must-identify-an-onlineversions-entr","errorCode":null,"errorMessage":"latestVersion must identify an onlineVersions entry","messagePattern":"latestVersion must identify an onlineVersions entry","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":267,"sourceCode":"        }\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);\n            validateProtocols(entry.getProtocols(), \"versionCatalog.protocols\");\n        }\n        if (!latestFound) {\n            throw new IllegalArgumentException(\n                \"latestVersion must identify an onlineVersions entry\");\n        }\n    }\n    \n    /**\n     * Validate a raw runtime Endpoint management snapshot.\n     *\n     * @param snapshot runtime Endpoint snapshot\n     * @throws IllegalArgumentException when the snapshot is invalid\n     */\n    public static void validateRuntimeEndpointSnapshot(RuntimeEndpointSnapshot snapshot) {\n        requireNonNull(snapshot, \"runtimeEndpointSnapshot\");\n        AgentValidationUtils.validateNamespaceId(snapshot.getNamespaceId());\n        AgentValidationUtils.validateAgentName(snapshot.getAgentName());\n        AgentValidationUtils.validateProtocol(snapshot.getProtocol());\n        AgentVersion selectedVersion = null;\n        if (snapshot.getVersion() != null) {\n            selectedVersion = AgentVersion.parse(snapshot.getVersion());","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L249-L285","documentation":"Thrown by validateVersionCatalog as an IllegalArgumentException when onlineVersions is non-empty but no entry's version value equals catalog.getLatestVersion(). The latestVersion pointer must reference an actual online entry.","triggerScenarios":"Passing a catalog where onlineVersions is populated but none of the entries' parsed version values equal latestVersion — e.g. latestVersion=\"2.0.0\" but the only online version is \"1.0.0\".","commonSituations":"A version was taken offline but latestVersion still points at it; latestVersion was set to a draft/offline version; a typo or mismatched format between latestVersion and the entry values.","solutions":["Set latestVersion to the value of the intended online entry, matching its exact string/format.","When a version goes offline, recompute latestVersion from the remaining online versions.","Re-validate after any status change that removes a version from onlineVersions."],"exampleFix":"// before\ncatalog.setOnlineVersions(List.of(entry(\"1.0.0\")));\ncatalog.setLatestVersion(\"2.0.0\"); // not in online set\nAgentModelValidator.validateVersionCatalog(catalog); // throws\n\n// after\ncatalog.setOnlineVersions(List.of(entry(\"1.0.0\")));\ncatalog.setLatestVersion(\"1.0.0\"); // matches an entry\nAgentModelValidator.validateVersionCatalog(catalog); // ok","handlingStrategy":"validation","validationCode":"String latest = catalog.getLatestVersion();\nboolean matches = catalog.getOnlineVersions().stream()\n    .map(e -> AgentVersion.parse(e.getVersion()).getValue())\n    .anyMatch(latest::equals);\nif (!matches) {\n    // point latest at the highest online version\n    catalog.setLatestVersion(catalog.getOnlineVersions().stream()\n        .map(e -> AgentVersion.parse(e.getVersion()).getValue())\n        .max(Comparator.naturalOrder()).orElse(null));\n}\nAgentModelValidator.validateVersionCatalog(catalog);","typeGuard":"static boolean latestPointsToOnline(AgentVersionCatalog catalog) {\n    if (catalog.getOnlineVersions() == null || catalog.getOnlineVersions().isEmpty()) return true;\n    String latest = catalog.getLatestVersion();\n    return catalog.getOnlineVersions().stream()\n        .map(e -> AgentVersion.parse(e.getVersion()).getValue())\n        .anyMatch(latest::equals);\n}","tryCatchPattern":null,"preventionTips":["Recompute latestVersion after any change to onlineVersions (offline/online transitions).","Use the exact version string from the entry as latestVersion to avoid format mismatches.","Unit-test catalog transitions: taking the latest offline must update latestVersion."],"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"}