alibaba/nacos · warning · IllegalArgumentException

pageNo and pageSize must be greater than zero

Error message

pageNo and pageSize must be greater than zero

What it means

Thrown by AuthEmbeddedPaginationHelperImpl.fetchPage (the embedded Derby variant) when pageNo or pageSize is less than or equal to zero. This is an input-validation guard on the pagination API before any SQL is executed. The method is used by auth controllers (user/role/permission listing) that delegate to the embedded database pagination helper.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/persistence/embedded/AuthEmbeddedPaginationHelperImpl.java:68

     * @param args         query args
     * @param pageNo       page number
     * @param pageSize     page size
     * @param rowMapper    Entity mapping
     * @return Paging data
     */
    @Override
    public Page<E> fetchPage(final String sqlCountRows, final String sqlFetchRows,
        final Object[] args,
        final int pageNo, final int pageSize, final RowMapper rowMapper) {
        return fetchPage(sqlCountRows, sqlFetchRows, args, pageNo, pageSize, null, rowMapper);
    }
    
    @Override
    public Page<E> fetchPage(final String sqlCountRows, final String sqlFetchRows, Object[] args,
        final int pageNo,
        final int pageSize, final Long lastMaxId, final RowMapper rowMapper) {
        if (pageNo <= 0 || pageSize <= 0) {
            throw new IllegalArgumentException("pageNo and pageSize must be greater than zero");
        }
        
        // Query the total number of current records
        Integer rowCountInt = databaseOperate.queryOne(sqlCountRows, args, Integer.class);
        if (rowCountInt == null) {
            throw new IllegalArgumentException("fetchPageLimit error");
        }
        
        // Count pages
        int pageCount = rowCountInt / pageSize;
        if (rowCountInt > pageSize * pageCount) {
            pageCount++;
        }
        
        // Create Page object
        final Page<E> page = new Page<>();
        page.setPageNumber(pageNo);
        page.setPagesAvailable(pageCount);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure pageNo starts at 1 and pageSize is at least 1 in all API calls.
2. Add client-side validation to default missing/zero pageNo to 1 and pageSize to a reasonable default (e.g., 20).
3. If building a custom controller, validate the form parameters before calling fetchPage and return a 400 with a clear message.

Example fix

// before
int pageNo = request.getParameter("pageNo") != null
    ? Integer.parseInt(request.getParameter("pageNo")) : 0;
Page<User> page = paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);

// after
int pageNo = request.getParameter("pageNo") != null
    ? Integer.parseInt(request.getParameter("pageNo")) : 1;
if (pageNo <= 0) pageNo = 1;
if (pageSize <= 0) pageSize = 20;
Page<User> page = paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);

// Validate pagination before calling fetchPage
if (pageNo <= 0 || pageSize <= 0) {
    throw new IllegalArgumentException("pageNo and pageSize must be >= 1");
}
Page<E> page = paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);

public static boolean isValidPagination(int pageNo, int pageSize) {
    return pageNo > 0 && pageSize > 0;
}

try {
    Page<E> page = paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("pageNo and pageSize")) {
        return ResponseEntity.badRequest().body("Invalid pagination parameters");
    }
    throw e;
}

When it happens

Trigger: An HTTP request to an admin auth listing endpoint (e.g., /v3/admin/auth/users with pageNo=0 or pageSize=-1) reaches the pagination helper. The guard triggers before the SQL count query runs. Also triggered if a default integer value of 0 is used when a request parameter is omitted.

Common situations: Frontend sends default page parameters as 0 before user interaction; API client library defaults pageNo to 0; test code passes uninitialized pagination values; URL query params parsed as 0 when missing.

Related errors

• fetchPageLimit error
• pageNo and pageSize must be greater than zero
• 500
• fetchPageLimit error
• role 'ROLE_ADMIN' is not permitted to delete!

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