alibaba/nacos · warning · NacosApiException

20002

Q: What causes "Required parameter 'pageNo' should be positive integer, current is %d" in alibaba/nacos?

Send pageNo >= 1 (Nacos pagination is 1-based).

20002

Error message

Required parameter 'pageNo' should be positive integer, current is %d

What it means

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.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/model/form/PageForm.java:40

import org.springframework.http.HttpStatus;

/**
 * Nacos HTTP page API form.
 *
 * @author xiweng.yy
 */
public class PageForm implements NacosForm {
    
    private static final long serialVersionUID = -8912131925234465033L;
    
    private int pageNo = 1;
    
    private int pageSize = 100;
    
    @Override
    public void validate() throws NacosApiException {
        if (pageNo < 1) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                String.format(
                    "Required parameter 'pageNo' should be positive integer, current is %d",
                    pageNo));
        }
        if (pageSize < 1) {
            throw new NacosApiException(HttpStatus.BAD_REQUEST.value(),
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                String.format(
                    "Required parameter 'pageSize' should be positive integer, current is %d",
                    pageSize));
        }
    }
    
    public int getPageNo() {
        return pageNo;
    }

View on GitHub (pinned to 9b989acdf1)

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.

Example fix

// before
GET /v3/console/ns/service/list?pageNo=0&pageSize=10
// after
GET /v3/console/ns/service/list?pageNo=1&pageSize=10

Defensive patterns

Strategy: validation

Validate before calling

// Java client: enforce 1-based paging before the call
int pageNo = requestedPageNo;
if (pageNo < 1) {
    pageNo = 1; // or throw IllegalArgumentException("pageNo must be >= 1");
}
String url = "/v3/console/ns/service/list?pageNo=" + pageNo + "&pageSize=" + pageSize;

Try / catch

// If you must rely on the server as the gatekeeper:
try {
    result = namingService ... list(pageNo, pageSize);
} catch (NacosApiException e) {
    if (e.getErrCode() == 20002 && e.getMessage().contains("pageNo")) {
        // fix paging and retry once
    } else { throw e; }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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