alibaba/nacos · error · IllegalArgumentException

onlineCnt must equal the number of onlineVersions entries

Error message

onlineCnt must equal the number of onlineVersions entries

What it means

Thrown by validateVersionInfoCatalogConsistency when AgentVersionInfo.onlineCnt does not equal versionCatalog.onlineVersions.size(). These two fields are redundant by design and must agree; a mismatch indicates a torn read or an incorrectly hand-assembled payload. This runs after the non-negativity check (error 484).

Source

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

            AgentValidationUtils.validateVersion(versionInfo.getReviewingVersion());
        }
        Integer onlineCount = versionInfo.getOnlineCnt();
        if (onlineCount == null || onlineCount < 0) {
            throw new IllegalArgumentException("onlineCnt must be a non-negative integer");
        }
        Map<String, String> labels = versionInfo.getLabels();
        requireNonNull(labels, "versionInfo.labels");
        for (Map.Entry<String, String> entry : labels.entrySet()) {
            AgentValidationUtils.validateLabel(entry.getKey());
            AgentValidationUtils.validateVersion(entry.getValue());
        }
    }
    
    private static void validateVersionInfoCatalogConsistency(AgentVersionInfo versionInfo,
        AgentVersionCatalog catalog) {
        List<AgentVersionCatalogEntry> onlineVersions = catalog.getOnlineVersions();
        if (versionInfo.getOnlineCnt() != onlineVersions.size()) {
            throw new IllegalArgumentException(
                "onlineCnt must equal the number of onlineVersions entries");
        }
        String editingVersion = versionInfo.getEditingVersion();
        String reviewingVersion = versionInfo.getReviewingVersion();
        if (editingVersion != null && editingVersion.equals(reviewingVersion)) {
            throw new IllegalArgumentException(
                "editingVersion and reviewingVersion must identify different Versions");
        }
        Set<String> onlineVersionValues = new HashSet<String>();
        for (AgentVersionCatalogEntry entry : onlineVersions) {
            onlineVersionValues.add(entry.getVersion());
        }
        if (onlineVersionValues.contains(editingVersion)
            || onlineVersionValues.contains(reviewingVersion)) {
            throw new IllegalArgumentException(
                "editingVersion and reviewingVersion must not identify online Versions");
        }
        for (Map.Entry<String, String> label : versionInfo.getLabels().entrySet()) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Set onlineCnt = versionCatalog.getOnlineVersions().size() right before validation/submission.
Never cache onlineCnt separately from the list; always derive it.
If loading from storage, recompute the count in the same transaction as the list.

Example fix

// before
versionInfo.setOnlineCnt(2); catalog.setOnlineVersions(List.of(entry1, entry2, entry3));
// after
versionInfo.setOnlineCnt(catalog.getOnlineVersions().size());

Defensive patterns

Strategy: validation

Validate before calling

static void syncOnlineCnt(AgentVersionInfo info, AgentVersionCatalog catalog) {
    info.setOnlineCnt(catalog.getOnlineVersions().size());
}

Type guard

static boolean onlineCntMatches(AgentVersionInfo info, AgentVersionCatalog catalog) {
    return info.getOnlineCnt() != null
        && info.getOnlineCnt() == catalog.getOnlineVersions().size();
}

Try / catch

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("onlineCnt must equal")) {
        agent.getVersionInfo().setOnlineCnt(
            agent.getVersionCatalog().getOnlineVersions().size());
    }
}

Prevention

Set onlineCnt = onlineVersions.size() in the same mutation that changes the list.
Never cache onlineCnt separately from the list.
Load both fields from the same transaction to avoid torn reads.

When it happens

Trigger: Submitting a payload where onlineCnt was cached/stale while the onlineVersions list was edited; setting onlineCnt by hand without recounting; reading onlineVersions from one store and onlineCnt from another in a race.

Common situations: Hand-building an Agent model for testing or migration and forgetting to keep the count in sync; a client that caches onlineCnt but recomputes the list.

Related errors

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