{"record":{"id":"1c421ad7926fb5ba","repo":"alibaba/nacos","slug":"10000-1c421a","errorCode":"10000","errorMessage":"Required parameter 'scope' type String is not present","messagePattern":"Required parameter 'scope' type String is not present","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecScopeForm.java","lineNumber":43,"sourceCode":"import java.io.Serial;\n\n/**\n * Form for updating agentspec visibility scope.\n *\n * @author nacos\n */\npublic class AgentSpecScopeForm extends AgentSpecForm {\n    \n    @Serial\n    private static final long serialVersionUID = 1L;\n    \n    private String scope;\n    \n    @Override\n    public void validate() throws NacosApiException {\n        super.validate();\n        if (StringUtils.isBlank(scope)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"Required parameter 'scope' type String is not present\");\n        }\n        if (!VisibilityConstants.SCOPE_PUBLIC.equalsIgnoreCase(scope)\n            && !VisibilityConstants.SCOPE_PRIVATE.equalsIgnoreCase(scope)) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                \"Parameter 'scope' must be PUBLIC or PRIVATE\");\n        }\n    }\n    \n    public String getScope() {\n        return scope;\n    }\n    \n    public void setScope(String scope) {\n        this.scope = scope;\n    }\n}","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/form/agentspecs/admin/AgentSpecScopeForm.java#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the `scope` parameter with value `PUBLIC` or `PRIVATE` to the request (form-encoded body or query string).","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.","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>'."],"exampleFix":"// before (fails)\ncurl -X PUT 'http://host/v3/admin/ai/agentspecs/scope' -d 'agentSpecName=mySpec'\n// after\ncurl -X PUT 'http://host/v3/admin/ai/agentspecs/scope' -d 'agentSpecName=mySpec&scope=PUBLIC'","handlingStrategy":"validation","validationCode":"String scope = params.get(\"scope\");\nif (scope == null || scope.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"scope is required\");\n}","typeGuard":"static boolean isValidScope(String s) {\n    return \"PUBLIC\".equalsIgnoreCase(s) || \"PRIVATE\".equalsIgnoreCase(s);\n}","tryCatchPattern":"// NacosApiException -> HTTP 400, code 10000\ncatch (NacosApiException e) {\n    if (e.getErrCode() == 10000 && e.getMessage().contains(\"'scope'\")) {\n        // prompt user to pick PUBLIC/PRIVATE\n    }\n}","preventionTips":["Pre-validate scope against {PUBLIC, PRIVATE} before the HTTP call.","Render scope as a fixed two-option control in the UI."],"tags":["validation","ai","agentspec","visibility","parameter","http","api"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}