What causes "Invalid Agent resource status: {status}" in alibaba/nacos?

Use AiConstants.Agent.RESOURCE_STATUS_ENABLE and RESOURCE_STATUS_DISABLE constants directly instead of hardcoding strings.

alibaba/nacos · error · IllegalArgumentException

Invalid Agent resource status: {status}

Error message

Invalid Agent resource status: {status}

What it means

AgentAdminRequestUtils.validateWritableStatus rejects any status string that is not exactly AiConstants.Agent.RESOURCE_STATUS_ENABLE or RESOURCE_STATUS_DISABLE. This is an XOR check on the two allowed writable status values for Agent resources.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/agent/AgentAdminRequestUtils.java:43

 * @author Nacos
 */
final class AgentAdminRequestUtils {
    
    private AgentAdminRequestUtils() {
    }
    
    static void validateIdentity(String agentName) {
        AgentValidationUtils.validateAgentName(agentName);
    }
    
    static void validateVersion(String version) {
        AgentValidationUtils.validateVersion(version);
    }
    
    static void validateWritableStatus(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);
        }
    }
    
    static boolean isBlank(String value) {
        if (value == null) {
            return true;
        }
        for (int i = 0; i < value.length(); i++) {
            if (!Character.isWhitespace(value.charAt(i))) {
                return false;
            }
        }
        return true;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Use AiConstants.Agent.RESOURCE_STATUS_ENABLE and RESOURCE_STATUS_DISABLE constants directly instead of hardcoding strings.
Map incoming user-facing values to the canonical constants before building the request.
Check the exact constant values in AiConstants.Agent if unsure of casing.

Example fix

// before
request.setStatus("enabled"); // wrong casing

// after
import com.alibaba.nacos.api.ai.constant.AiConstants;
request.setStatus(AiConstants.Agent.RESOURCE_STATUS_ENABLE);

Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> VALID_STATUSES = Set.of(
    AiConstants.Agent.RESOURCE_STATUS_ENABLE,
    AiConstants.Agent.RESOURCE_STATUS_DISABLE);

if (!VALID_STATUSES.contains(status)) {
    throw new IllegalArgumentException(
        "Status must be ENABLE or DISABLE, got: " + status);
}

Type guard

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

Try / catch

try {
    request.validate();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Invalid Agent resource status")) {
        // map to canonical status or return 400 to caller
        return ResponseEntity.badRequest().body(e.getMessage());
    }
    throw e;
}

Prevention

Always use AiConstants.Agent constants instead of string literals.
Validate at the API boundary before constructing request objects.
Document the exact accepted status values in your API contract.

When it happens

Trigger: Passing a status like 'ENABLED', 'enabled', 'on', 'off', '1', '0', or any arbitrary string to a draft/status update request that calls validateWritableStatus internally. Case sensitivity matters: only the exact constant values are accepted.

Common situations: Frontend or API client sends 'enabled' (lowercase) instead of the canonical constant. A migration script uses different status vocabulary. Misreading the API docs and guessing status values.

Related errors

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