alibaba/nacos · error · IllegalArgumentException

Invalid Agent resource status: {status}

Error message

Invalid Agent resource status: {status}

What it means

Thrown by the private validateResourceStatus as an IllegalArgumentException when the agent's status field is neither RESOURCE_STATUS_ENABLE nor RESOURCE_STATUS_DISABLE (defined in AiConstants.Agent). Status governs whether the agent resource is active.

Source

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

        if (provider == null) {
            return;
        }
        validateRequiredLength(provider.getName(), MAX_PROVIDER_NAME_LENGTH, "provider.name");
        if (provider.getUrl() != null) {
            validateAbsoluteUri(provider.getUrl(), "provider.url");
        }
    }
    
    private static void validateScope(String scope) {
        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) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Map the agent's status to AiConstants.Agent.RESOURCE_STATUS_ENABLE or RESOURCE_STATUS_DISABLE before validation.
2. Default new agents to ENABLE (or DISABLE) rather than leaving status null.
3. Normalize incoming status strings to the canonical constants at the integration boundary.

Example fix

// before
agent.setStatus("ACTIVE");
AgentModelValidator.validateAgent(agent); // throws

// after
import com.alibaba.nacos.api.ai.constant.AiConstants;
agent.setStatus(AiConstants.Agent.RESOURCE_STATUS_ENABLE);
AgentModelValidator.validateAgent(agent); // ok

import com.alibaba.nacos.api.ai.constant.AiConstants;
static final Set<String> STATUSES = Set.of(
    AiConstants.Agent.RESOURCE_STATUS_ENABLE,
    AiConstants.Agent.RESOURCE_STATUS_DISABLE);
if (!STATUSES.contains(agent.getStatus())) {
    agent.setStatus(AiConstants.Agent.RESOURCE_STATUS_DISABLE);
}
AgentModelValidator.validateAgent(agent);

static boolean isValidResourceStatus(String status) {
    return AiConstants.Agent.RESOURCE_STATUS_ENABLE.equals(status)
        || AiConstants.Agent.RESOURCE_STATUS_DISABLE.equals(status);
}

When it happens

Trigger: Calling validateAgent/validateAgentSummary when agent.getStatus() is null or any value other than the ENABLE/DISABLE constants — e.g. "ACTIVE", "enabled", "1", or a custom lifecycle state.

Common situations: A legacy client sent an old status vocabulary; status was left null on create; an external system synced an agent with its own status enum that doesn't map to Nacos values.

Related errors

• scope must be PUBLIC or PRIVATE
• Invalid Version page metadata
• versionPage.pageItems exceeds {MAX_VERSION_PAGE_ITEMS} items
• latestVersion must be absent when onlineVersions is empty
• Duplicate online Agent Version: {version.value}

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