alibaba/nacos · error · IllegalArgumentException

Invalid Agent Version status: {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.

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)

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

• 20002
• 10000
• 20002
• 10000
• 20002

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