{"record":{"id":"07f357e7a5ba7a96","repo":"alibaba/nacos","slug":"20002-07f357","errorCode":"20002","errorMessage":"Required parameter 'pageNo' should be positive integer, current is %d","messagePattern":"Required parameter 'pageNo' should be positive integer, current is (.+?)","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"warning","filePath":"core/src/main/java/com/alibaba/nacos/core/model/form/PageForm.java","lineNumber":40,"sourceCode":"import org.springframework.http.HttpStatus;\n\n/**\n * Nacos HTTP page API form.\n *\n * @author xiweng.yy\n */\npublic class PageForm implements NacosForm {\n    \n    private static final long serialVersionUID = -8912131925234465033L;\n    \n    private int pageNo = 1;\n    \n    private int pageSize = 100;\n    \n    @Override\n    public void validate() throws NacosApiException {\n        if (pageNo < 1) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                String.format(\n                    \"Required parameter 'pageNo' should be positive integer, current is %d\",\n                    pageNo));\n        }\n        if (pageSize < 1) {\n            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),\n                ErrorCode.PARAMETER_VALIDATE_ERROR,\n                String.format(\n                    \"Required parameter 'pageSize' should be positive integer, current is %d\",\n                    pageSize));\n        }\n    }\n    \n    public int getPageNo() {\n        return pageNo;\n    }\n    ","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/core/src/main/java/com/alibaba/nacos/core/model/form/PageForm.java#L22-L58","documentation":"PageForm.validate() rejects a non-positive pageNo: the form defaults pageNo=1, pageSize=100, and throws NacosApiException with HTTP 400 / ErrorCode.PARAMETER_VALIDATE_ERROR (20002) whenever pageNo < 1. This single form backs every paginated v3 list API on the server (services, configs, history, subscribers, AI agents/skills/MCP/A2A/agentspec/pipelines), so the same check fires across many endpoints.","triggerScenarios":"Calling any GET list endpoint with pageNo=0 or a negative value, e.g. GET /v3/console/ns/service/list?pageNo=0&pageSize=10, GET /v3/console/cs/config/list?pageNo=0, GET /v3/admin/ai/agent/list?pageNo=0. Spring binds the value into PageForm and validate() throws before the query runs.","commonSituations":"Client treating pageNo as 0-based instead of Nacos' 1-based convention; a UI/loop that passes a zero-indexed counter straight into pageNo; a request builder that omits pageNo and a proxy/gateway rewrites it to 0.","solutions":["Send pageNo >= 1 (Nacos pagination is 1-based).","If you do not need a specific page, omit pageNo so the server uses its default of 1.","Validate pageNo > 0 in the client before issuing the request."],"exampleFix":"// before\nGET /v3/console/ns/service/list?pageNo=0&pageSize=10\n// after\nGET /v3/console/ns/service/list?pageNo=1&pageSize=10","handlingStrategy":"validation","validationCode":"// Java client: enforce 1-based paging before the call\nint pageNo = requestedPageNo;\nif (pageNo < 1) {\n    pageNo = 1; // or throw IllegalArgumentException(\"pageNo must be >= 1\");\n}\nString url = \"/v3/console/ns/service/list?pageNo=\" + pageNo + \"&pageSize=\" + pageSize;","typeGuard":null,"tryCatchPattern":"// If you must rely on the server as the gatekeeper:\ntry {\n    result = namingService ... list(pageNo, pageSize);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == 20002 && e.getMessage().contains(\"pageNo\")) {\n        // fix paging and retry once\n    } else { throw e; }\n}","preventionTips":["Treat Nacos pageNo as 1-based everywhere.","Centralize pagination building in one helper that clamps pageNo>=1, pageSize>=1.","Default omitted paging params rather than passing 0."],"tags":["pagination","validation","http-api","client-error"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}