alibaba/nacos · error · IllegalArgumentException

Invalid Agent Version status

Error message

Invalid Agent Version status: {status}

What it means

Thrown by AgentModelValidator.validateVersionStatus when an Agent Version's status is not one of the five allowed lifecycle values. The Agent Version lifecycle is an enum-like string contract: draft, reviewing, reviewed, online, offline. Any other string (including typos, uppercase variants, or null passed through string concat) is rejected because the server state machine cannot transition to an unknown status.

Solutions

1. Set the Version status to one of the exact lowercase constants: draft, reviewing, reviewed, online, or offline.
2. If you build the value from an enum, map it with AiConstants.Agent.VERSION_STATUS_* rather than enum.name().toLowerCase().
3. Do not reuse Agent resource status values (enable/disable) for Version status.
4. Grep your client code for any place that constructs a Version status dynamically and harden it against unknown inputs.

Example fix

// before
versionSummary.setStatus("enabled");
// after
versionSummary.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE); // "online"

private static final Set<String> VERSION_STATUSES = Set.of(
    AiConstants.Agent.VERSION_STATUS_DRAFT,
    AiConstants.Agent.VERSION_STATUS_REVIEWING,
    AiConstants.Agent.VERSION_STATUS_REVIEWED,
    AiConstants.Agent.VERSION_STATUS_ONLINE,
    AiConstants.Agent.VERSION_STATUS_OFFLINE);

static String checkVersionStatus(String status) {
    if (!VERSION_STATUSES.contains(status)) {
        throw new IllegalArgumentException("Unknown Version status: " + status);
    }
    return status;
}

static boolean isValidVersionStatus(String s) {
    return s != null && Set.of("draft", "reviewing", "reviewed", "online", "offline").contains(s);
}

try {
    AgentModelValidator.validateVersionSummary(summary);
} catch (IllegalArgumentException e) {
    // log and surface a 400 to the client with the validator's message
}

When it happens

Trigger: Calling validateVersionSummary or validateVersionDetail with a Version whose status field is e.g. "enabled", "PUBLISHED", "on", "", or a localized string. Also triggered when a client SDK serializes a status enum as its name() but the server expects lowercase constants.

Common situations: Migrating from an older Nacos AI registry that accepted free-form status strings; integrating a non-Java client that sends uppercase enum names; copy-pasting an Agent resource status (enable/disable) into a Version status field, since resource status and version status are different vocabularies.

Related errors

• 10000
• 10000
• 10000
• 10000
• 10000

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

Appendix: source

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

        if (!"PUBLIC".equals(scope) && !"PRIVATE".equals(scope)) {
            throw new IllegalArgumentException("scope must be PUBLIC or PRIVATE");
        }
    }
    
    private static void validateResourceStatus(String status) {
        if (!AiConstants.Agent.RESOURCE_STATUS_ENABLE.equals(status)
            && !AiConstants.Agent.RESOURCE_STATUS_DISABLE.equals(status)) {
            throw new IllegalArgumentException("Invalid Agent resource status: " + status);
        }
    }
    
    private static void validateVersionStatus(String status) {
        if (!AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {
            throw new IllegalArgumentException("Invalid Agent Version status: " + status);
        }
    }
    
    private static void validateTags(List<String> tags) {
        if (tags == null) {
            return;
        }
        if (tags.size() > MAX_TAGS) {
            throw new IllegalArgumentException("tags exceeds " + MAX_TAGS + " items");
        }
        Set<String> uniqueTags = new HashSet<String>();
        for (String tag : tags) {
            validateRequiredLength(tag, MAX_TAG_LENGTH, "tag");
            if (!uniqueTags.add(tag)) {
                throw new IllegalArgumentException("Duplicate tag: " + tag);
            }
        }
    }

View on GitHub (pinned to 9b989acdf1)