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.

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)

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

• latestVersion must be absent when onlineVersions is empty
• Duplicate online Agent Version: {version.value}
• Invalid Version page metadata
• versionPage.pageItems exceeds {MAX_VERSION_PAGE_ITEMS} items
• runtimeEndpointSnapshot.items exceeds {MAX_RUNTIME_ENDPOINTS

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