alibaba/nacos · error · IllegalArgumentException

latestVersion must be absent when onlineVersions is empty

Error message

latestVersion must be absent when onlineVersions is empty

What it means

Thrown by AgentModelValidator.validateVersionCatalog as an IllegalArgumentException when the catalog's onlineVersions list is empty but latestVersion is non-null. An empty catalog cannot have a 'latest' version, so the two fields are mutually exclusive in that state.

Source

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

     * @throws IllegalArgumentException when the CallInterface is invalid
     */
    public static void validateCallInterface(AgentCallInterface callInterface) {
        validateCallInterface("validation", "validation", callInterface);
    }
    
    /**
     * Validate the compact catalog of online Agent Versions.
     *
     * @param catalog Agent Version catalog
     * @throws IllegalArgumentException when the catalog is invalid
     */
    public static void validateVersionCatalog(AgentVersionCatalog catalog) {
        requireNonNull(catalog, "versionCatalog");
        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);

View on GitHub (pinned to 9b989acdf1)

Solutions

Set catalog.setLatestVersion(null) whenever onlineVersions is empty.
When taking the last version offline, clear latestVersion in the same update.
Build the catalog so latestVersion is derived from onlineVersions rather than set independently.

Example fix

// before
AgentVersionCatalog catalog = new AgentVersionCatalog();
catalog.setOnlineVersions(Collections.emptyList());
catalog.setLatestVersion("1.0.0");
AgentModelValidator.validateVersionCatalog(catalog); // throws

// after
AgentVersionCatalog catalog = new AgentVersionCatalog();
catalog.setOnlineVersions(Collections.emptyList());
catalog.setLatestVersion(null);
AgentModelValidator.validateVersionCatalog(catalog); // ok

Defensive patterns

Strategy: validation

Validate before calling

if (catalog.getOnlineVersions() == null || catalog.getOnlineVersions().isEmpty()) {
    catalog.setLatestVersion(null);
}
AgentModelValidator.validateVersionCatalog(catalog);

Type guard

static boolean catalogIsEmptyConsistent(AgentVersionCatalog catalog) {
    boolean empty = catalog.getOnlineVersions() == null || catalog.getOnlineVersions().isEmpty();
    return !empty || catalog.getLatestVersion() == null;
}

Prevention

Clear latestVersion atomically when the last online version is removed.
Derive latestVersion from onlineVersions rather than maintaining it independently.
Treat the empty-catalog + non-null-latest state as a data bug to fix at the source.

When it happens

Trigger: Calling validateVersionCatalog with a catalog where getOnlineVersions() is empty AND getLatestVersion() != null.

Common situations: All versions were taken offline but latestVersion was not cleared; a newly-created agent has no online versions yet but a stale latestVersion pointer; a serialization default left latestVersion set.

Related errors

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