alibaba/nacos · error · NacosApiException

20002

20002

Error message

Request parameter `scope` must be PUBLIC or PRIVATE.

What it means

Thrown by AgentValidationUtils.validateAgentName when the name is 1-64 chars long and every character is printable ASCII (0x20-0x7E) but contains no character above 0x20 (i.e. it is all spaces). The same 'Invalid agentName' text is also used at line 89 (null/empty/>64) and line 95 (out-of-range char), but line 102 specifically rejects all-whitespace names. The validator requires at least one visible character.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/AiResourceFilterableForm.java:80

     * When {@code null} or empty, no scope filter is applied and both public and private
     * resources that the caller is authorized to see are returned.</p>
     */
    private String scope;
    
    /**
     * Optional filter by business tag.
     *
     * <p>When specified, only resources whose {@code bizTags} column contains the given value
     * are returned (fuzzy match). When {@code null} or empty, no bizTag filter is applied.</p>
     */
    private String bizTag;
    
    @Override
    public void validate() throws NacosApiException {
        if (StringUtils.isNotBlank(scope)
            && !VisibilityConstants.SCOPE_PUBLIC.equalsIgnoreCase(scope)
            && !VisibilityConstants.SCOPE_PRIVATE.equalsIgnoreCase(scope)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Request parameter `scope` must be PUBLIC or PRIVATE.");
        }
    }
    
    public String getOwner() {
        return owner;
    }
    
    public void setOwner(String owner) {
        this.owner = owner;
    }
    
    public String getScope() {
        return scope;
    }
    
    public void setScope(String scope) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Trim the agentName and confirm at least one non-space printable ASCII character remains before submitting.
2. Reject blank/whitespace input at the controller/form boundary so it never reaches AgentValidationUtils.
3. Restrict agentName to [A-Za-z0-9 _-]-style tokens of 1-64 chars.

Example fix

// before
form.setAgentName("   ");
// after
String name = form.getAgentName() == null ? "" : form.getAgentName().trim();
if (name.isEmpty()) {
    throw new IllegalArgumentException("agentName is required");
}
form.setAgentName(name);

String name = agentName == null ? null : agentName.trim();
if (name == null || name.isEmpty() || name.length() > 64
        || !name.matches("^[\\x20-\\x7E]*$")
        || name.chars().allMatch(c -> c == 0x20)) {
    throw new IllegalArgumentException("Invalid agentName");
}

static boolean isValidAgentName(String s) {
    return s != null && !s.isEmpty() && s.length() <= 64
        && s.chars().allMatch(c -> c >= 0x20 && c <= 0x7E)
        && s.chars().anyMatch(c -> c > 0x20);
}

try {
    AgentValidationUtils.validateAgentName(agentName);
} catch (IllegalArgumentException e) {
    // map to HTTP 400 with field 'agentName'
}

When it happens

Trigger: Submitting an Agent create/update form (AgentAdminForm.validate at ai/.../form/agent/admin/AgentAdminForm.java:44) or calling AgentPersistenceService/AgentOperationService with agentName set to whitespace only (e.g. " "). Also RadAsciiAgentIdCodec.decode when an encoded agent id decodes to an all-space name.

Common situations: Trimming is applied at the wrong layer so spaces survive to the validator; a UI field auto-filled with spaces; copy-paste of a name that ended up entirely spaces; test fixtures using " " as a placeholder.

Related errors

• 10000
• 20002
• 10000
• 20002
• 20002

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