alibaba/nacos · error · NacosApiException

20002

20002

Error message

Parameter 'scope' must be PUBLIC or PRIVATE

What it means

Thrown by AgentSpecScopeForm.validate() when `scope` is present but is neither PUBLIC nor PRIVATE (case-insensitive). This is the value-domain check that runs after the presence check. It maps to error code 20002 (PARAMETER_VALIDATE_ERROR) and HTTP 400. The valid values are defined in VisibilityConstants (SCOPE_PUBLIC="PUBLIC", SCOPE_PRIVATE="PRIVATE").

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecScopeForm.java:48

 * @author nacos
 */
public class AgentSpecScopeForm extends AgentSpecForm {
    
    @Serial
    private static final long serialVersionUID = 1L;
    
    private String scope;
    
    @Override
    public void validate() throws NacosApiException {
        super.validate();
        if (StringUtils.isBlank(scope)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Required parameter 'scope' type String is not present");
        }
        if (!VisibilityConstants.SCOPE_PUBLIC.equalsIgnoreCase(scope)
            && !VisibilityConstants.SCOPE_PRIVATE.equalsIgnoreCase(scope)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Parameter 'scope' must be PUBLIC or PRIVATE");
        }
    }
    
    public String getScope() {
        return scope;
    }
    
    public void setScope(String scope) {
        this.scope = scope;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set scope to exactly PUBLIC or PRIVATE (any case).
2. Audit the calling code/config for the scope value being sent and correct it to one of the two allowed constants.
3. Document the allowed set in the client's API wrapper to prevent recurrence.

Example fix

// before (fails)
scope=public-readonly
// after
scope=PUBLIC

if (!"PUBLIC".equalsIgnoreCase(scope) && !"PRIVATE".equalsIgnoreCase(scope)) {
    throw new IllegalArgumentException("scope must be PUBLIC or PRIVATE");
}

static boolean isValidScope(String s) {
    return "PUBLIC".equalsIgnoreCase(s) || "PRIVATE".equalsIgnoreCase(s);
}

catch (NacosApiException e) {
    if (e.getErrCode() == 20002) { /* invalid scope value */ }
}

When it happens

Trigger: Calling PUT /v3/admin/ai/agentspecs/scope with scope=public-readonly, scope=shared, scope=internal, or any value other than PUBLIC/PRIVATE. Comparison is case-insensitive so 'public' and 'Public' pass.

Common situations: Client hardcodes an older/different scope vocabulary (e.g. 'READONLY', 'TEAM'); typo in a config file; passing a numeric or boolean representation.

Related errors

• 10000
• 10000
• 10000
• 10000
• 10000

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