alibaba/nacos · error · NacosApiException

10000

10000

Error message

Required parameter 'scope' type String is not present

What it means

Thrown by AgentSpecScopeForm.validate() when the `scope` field is blank/null. This is a server-side form validation guard on the AgentSpec admin API (Nacos AI module) that runs before the visibility-scope update proceeds. It maps to error code 10000 (PARAMETER_MISSING) and HTTP 400 (INVALID_PARAM). The check uses StringUtils.isBlank, so empty string, whitespace, and null all trigger it.

Source

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

import java.io.Serial;

/**
 * Form for updating agentspec visibility scope.
 *
 * @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. Add the `scope` parameter with value `PUBLIC` or `PRIVATE` to the request (form-encoded body or query string).
2. Confirm the request Content-Type is application/x-www-form-urlencoded (or multipart) so Spring binds the form field; a JSON body will not populate it.
3. If calling via curl: curl -X PUT 'http://host:8848/v3/admin/ai/agentspecs/scope' -d 'namespaceId=public&agentSpecName=mySpec&scope=PUBLIC' -H 'Authorization: Bearer <token>'.

Example fix

// before (fails)
curl -X PUT 'http://host/v3/admin/ai/agentspecs/scope' -d 'agentSpecName=mySpec'
// after
curl -X PUT 'http://host/v3/admin/ai/agentspecs/scope' -d 'agentSpecName=mySpec&scope=PUBLIC'

String scope = params.get("scope");
if (scope == null || scope.trim().isEmpty()) {
    throw new IllegalArgumentException("scope is required");
}

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

// NacosApiException -> HTTP 400, code 10000
catch (NacosApiException e) {
    if (e.getErrCode() == 10000 && e.getMessage().contains("'scope'")) {
        // prompt user to pick PUBLIC/PRIVATE
    }
}

When it happens

Trigger: Calling PUT /v3/admin/ai/agentspecs/scope without the `scope` query/form parameter, or with scope="" / scope=" ". The controller AgentSpecAdminController.updateScope() invokes form.validate() which calls super.validate() (checks agentSpecName) then this scope-present check.

Common situations: Frontend form submits the scope toggle before a radio-button value is selected; a migration script or curl call omits scope assuming a default; client sends JSON body instead of form-encoded params so Spring does not bind scope.

Related errors

• 20002
• 10000
• 10000
• 10000
• 10000

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