alibaba/nacos · error · IllegalArgumentException

Agent scope must be PUBLIC or PRIVATE

Error message

Agent scope must be PUBLIC or PRIVATE

What it means

Error "Agent scope must be PUBLIC or PRIVATE" thrown in alibaba/nacos.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java:986

    private boolean hasInitialAgentMetadata(AgentDraftCreateRequest request) {
        return request.getDisplayName() != null || request.getDescription() != null
            || request.getIconUrl() != null || request.getProvider() != null
            || request.getTags() != null || request.getExtensions() != null;
    }
    
    private void validateListFilters(String agentNameContains, String tag, String scope,
        String orderBy) {
        if (StringUtils.isNotEmpty(agentNameContains)) {
            AgentValidationUtils.validateAgentName(agentNameContains);
        }
        if (StringUtils.isNotBlank(tag)
            && tag.codePointCount(0, tag.length()) > MAX_TAG_LENGTH) {
            throw new IllegalArgumentException("Invalid Agent tag filter: " + tag);
        }
        if (StringUtils.isNotBlank(scope)
            && !VisibilityConstants.SCOPE_PUBLIC.equals(scope)
            && !VisibilityConstants.SCOPE_PRIVATE.equals(scope)) {
            throw new IllegalArgumentException("Agent scope must be PUBLIC or PRIVATE");
        }
        if (StringUtils.isNotBlank(orderBy) && !"download_count".equals(orderBy)) {
            throw new IllegalArgumentException("Unsupported Agent orderBy: " + orderBy);
        }
    }
    
    private NacosApiException illegalState(String message) {
        return new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.ILLEGAL_STATE,
            message);
    }
    
    private NacosApiException conflict(String message) {
        return new NacosApiException(NacosException.CONFLICT, ErrorCode.RESOURCE_CONFLICT,
            message);
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Correct the invalid value for agent scope to match the expected format or allowed set, then retry.

When it happens

Trigger: Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java:986 when the library encounters an invalid state.

Common situations: Setting an Agent scope to a value other than PUBLIC or PRIVATE.

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