alibaba/nacos · error · IllegalArgumentException

scope must be PUBLIC or PRIVATE

Error message

scope must be PUBLIC or PRIVATE

What it means

Thrown by the private validateScope as an IllegalArgumentException when the agent's scope field is not exactly "PUBLIC" or "PRIVATE". Scope controls visibility of the agent resource across the namespace and is a required, enumerated field.

Source

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

        validateVersionInfoCatalogConsistency(versionInfo, versionCatalog);
        validateEpochMillis(metaVersion, "metaVersion");
        validateEpochMillis(createTime, "createTime");
        validateEpochMillis(updateTime, "updateTime");
    }
    
    private static void validateProvider(AgentProvider provider) {
        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);
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set scope to exactly "PUBLIC" or "PRIVATE" (uppercase) when creating or updating the agent.
2. Use the AiConstants scope constant if one exists, or centralize the allowed values.
3. Validate scope at the API boundary and reject/normalize before reaching the model validator.

Example fix

// before
agent.setScope("public"); // wrong case
AgentModelValidator.validateAgent(agent); // throws

// after
agent.setScope("PUBLIC");
// or
agent.setScope("PRIVATE");
AgentModelValidator.validateAgent(agent); // ok

static final Set<String> SCOPES = Set.of("PUBLIC", "PRIVATE");
if (!SCOPES.contains(agent.getScope())) {
    agent.setScope("PRIVATE"); // safe default
}
AgentModelValidator.validateAgent(agent);

static boolean isValidScope(String scope) {
    return "PUBLIC".equals(scope) || "PRIVATE".equals(scope);
}

When it happens

Trigger: Calling validateAgent or validateAgentSummary (which call validateScope internally) when agent.getScope() is null, empty, or any value other than "PUBLIC"/"PRIVATE" (e.g. "public", "Shared", "ORG").

Common situations: The scope was omitted (null) in a create/update payload; a client sent lowercase "public" instead of uppercase; a new scope concept was introduced but not yet supported by this validator version.

Related errors

• Invalid Agent resource status: {status}
• 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/5b6136697939731d. Report an issue: GitHub.