alibaba/nacos · error · IllegalArgumentException

onlineCnt must be a non-negative integer

Error message

onlineCnt must be a non-negative integer

What it means

Thrown by validateVersionInfo when AgentVersionInfo.onlineCnt is null or negative. onlineCnt is the cached count of currently-online Versions for the Agent and must be a non-negative integer. It is a denormalized field that the catalog-consistency check (error 485) will subsequently require to equal onlineVersions.size().

Source

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

            throw new IllegalArgumentException(
                "extensions exceeds " + MAX_EXTENSIONS + " entries");
        }
        for (String key : extensions.keySet()) {
            validateRequiredLength(key, MAX_EXTENSION_KEY_LENGTH, "extension key");
        }
    }
    
    private static void validateVersionInfo(AgentVersionInfo versionInfo) {
        requireNonNull(versionInfo, "versionInfo");
        if (versionInfo.getEditingVersion() != null) {
            AgentValidationUtils.validateVersion(versionInfo.getEditingVersion());
        }
        if (versionInfo.getReviewingVersion() != null) {
            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();

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Set onlineCnt to a non-negative integer, ideally the exact size of the online Versions list.
  2. For a fresh Agent with no online Versions, set onlineCnt = 0 explicitly.
  3. If you compute it from a query, default the empty result to 0 rather than null.

Example fix

// before
versionInfo.setOnlineCnt(null);
// after
versionInfo.setOnlineCnt(0);
Defensive patterns

Strategy: validation

Validate before calling

static int normalizeOnlineCnt(Integer raw) {
    if (raw == null || raw < 0) {
        throw new IllegalArgumentException("onlineCnt must be a non-negative integer");
    }
    return raw;
}

Type guard

static boolean isValidOnlineCnt(Integer c) {
    return c != null && c >= 0;
}

Try / catch

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("onlineCnt must be a non-negative")) {
        agent.getVersionInfo().setOnlineCnt(0);
    }
}

Prevention

When it happens

Trigger: Constructing an AgentVersionInfo with onlineCnt left null (default), set to -1, or computed from a query that returned no rows and was assigned a sentinel value.

Common situations: Building the versionInfo client-side for a create operation where there are no online versions yet but the field was omitted rather than set to 0; deserializing a malformed payload where the count arrived as null.

Related errors

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