alibaba/nacos · error · IllegalArgumentException

Duplicate online Agent Version: {version.value}

Error message

Duplicate online Agent Version: {version.value}

What it means

Thrown by validateVersionCatalog as an IllegalArgumentException when two entries in onlineVersions resolve to the same version value. The catalog requires unique versions; duplicates would make routing and 'latest' resolution ambiguous.

Source

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

        List<AgentVersionCatalogEntry> versions = catalog.getOnlineVersions();
        requireNonNull(versions, "versionCatalog.onlineVersions");
        if (versions.isEmpty()) {
            if (catalog.getLatestVersion() != null) {
                throw new IllegalArgumentException(
                    "latestVersion must be absent when onlineVersions is empty");
            }
            return;
        }
        
        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
     */

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Deduplicate onlineVersions by version value before validation.
2. When adding a version, check for an existing equal value first and update instead of inserting.
3. If different spellings normalize to the same value, canonicalize all version strings.

Example fix

// before
List<AgentVersionCatalogEntry> versions = List.of(
    entry("1.2.0"), entry("1.2.0"));
catalog.setOnlineVersions(versions);
AgentModelValidator.validateVersionCatalog(catalog); // throws

// after
List<AgentVersionCatalogEntry> versions = versions.stream()
    .collect(Collectors.toMap(
        e -> AgentVersion.parse(e.getVersion()).getValue(),
        Function.identity(), (a, b) -> a))
    .values().stream().toList();
catalog.setOnlineVersions(versions);
AgentModelValidator.validateVersionCatalog(catalog); // ok

Set<String> seen = new HashSet<>();
List<AgentVersionCatalogEntry> dedup = new ArrayList<>();
for (AgentVersionCatalogEntry e : catalog.getOnlineVersions()) {
    if (seen.add(AgentVersion.parse(e.getVersion()).getValue())) dedup.add(e);
}
catalog.setOnlineVersions(dedup);
AgentModelValidator.validateVersionCatalog(catalog);

static boolean versionsAreUnique(List<AgentVersionCatalogEntry> entries) {
    Set<String> vals = new HashSet<>();
    for (AgentVersionCatalogEntry e : entries) {
        if (!vals.add(AgentVersion.parse(e.getVersion()).getValue())) return false;
    }
    return true;
}

When it happens

Trigger: Passing a catalog whose onlineVersions contains two AgentVersionCatalogEntry items whose parsed AgentVersion.getValue() are equal (e.g. both "1.2.0").

Common situations: A version was added twice due to a retry/race; two entries used different strings ("1.2" and "1.2.0") that normalize to the same value; a migration script merged catalogs and created overlaps.

Related errors

• latestVersion must be absent when onlineVersions is empty
• latestVersion must identify an onlineVersions entry
• 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/465ccbfb5781f931. Report an issue: GitHub.