alibaba/nacos · error · IllegalArgumentException

latestVersion must identify an onlineVersions entry

Error message

latestVersion must identify an onlineVersions entry

What it means

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.

Solutions

1. Set latestVersion to the value of the intended online entry, matching its exact string/format.
2. When a version goes offline, recompute latestVersion from the remaining online versions.
3. Re-validate after any status change that removes a version from onlineVersions.

Example fix

// before
catalog.setOnlineVersions(List.of(entry("1.0.0")));
catalog.setLatestVersion("2.0.0"); // not in online set
AgentModelValidator.validateVersionCatalog(catalog); // throws

// after
catalog.setOnlineVersions(List.of(entry("1.0.0")));
catalog.setLatestVersion("1.0.0"); // matches an entry
AgentModelValidator.validateVersionCatalog(catalog); // ok

String latest = catalog.getLatestVersion();
boolean matches = catalog.getOnlineVersions().stream()
    .map(e -> AgentVersion.parse(e.getVersion()).getValue())
    .anyMatch(latest::equals);
if (!matches) {
    // point latest at the highest online version
    catalog.setLatestVersion(catalog.getOnlineVersions().stream()
        .map(e -> AgentVersion.parse(e.getVersion()).getValue())
        .max(Comparator.naturalOrder()).orElse(null));
}
AgentModelValidator.validateVersionCatalog(catalog);

static boolean latestPointsToOnline(AgentVersionCatalog catalog) {
    if (catalog.getOnlineVersions() == null || catalog.getOnlineVersions().isEmpty()) return true;
    String latest = catalog.getLatestVersion();
    return catalog.getOnlineVersions().stream()
        .map(e -> AgentVersion.parse(e.getVersion()).getValue())
        .anyMatch(latest::equals);
}

When it happens

Trigger: 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".

Common situations: 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.

Related errors

• Duplicate online Agent Version
• latestVersion must be absent when onlineVersions is empty
• Invalid Agent resource status
• Invalid Version page metadata
• runtimeEndpointSnapshot.items exceeds

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/0fb9ce1a01f66b4a. Report an issue: GitHub.

Appendix: source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:267

        }
        
        AgentValidationUtils.validateVersion(catalog.getLatestVersion());
        Set<String> versionValues = new HashSet<String>();
        Set<String> labelValues = new HashSet<String>();
        boolean latestFound = false;
        for (AgentVersionCatalogEntry entry : versions) {
            requireNonNull(entry, "versionCatalog entry");
            AgentVersion version = AgentVersion.parse(entry.getVersion());
            if (!versionValues.add(version.getValue())) {
                throw new IllegalArgumentException(
                    "Duplicate online Agent Version: " + version.getValue());
            }
            latestFound |= catalog.getLatestVersion().equals(version.getValue());
            validateCatalogLabels(entry.getLabels(), labelValues);
            validateProtocols(entry.getProtocols(), "versionCatalog.protocols");
        }
        if (!latestFound) {
            throw new IllegalArgumentException(
                "latestVersion must identify an onlineVersions entry");
        }
    }
    
    /**
     * Validate a raw runtime Endpoint management snapshot.
     *
     * @param snapshot runtime Endpoint snapshot
     * @throws IllegalArgumentException when the snapshot is invalid
     */
    public static void validateRuntimeEndpointSnapshot(RuntimeEndpointSnapshot snapshot) {
        requireNonNull(snapshot, "runtimeEndpointSnapshot");
        AgentValidationUtils.validateNamespaceId(snapshot.getNamespaceId());
        AgentValidationUtils.validateAgentName(snapshot.getAgentName());
        AgentValidationUtils.validateProtocol(snapshot.getProtocol());
        AgentVersion selectedVersion = null;
        if (snapshot.getVersion() != null) {
            selectedVersion = AgentVersion.parse(snapshot.getVersion());

View on GitHub (pinned to 9b989acdf1)