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 AuthExternalPaginationHelperImpl.fetchPage (the external MySQL/PostgreSQL variant) when pageNo or pageSize is <= 0. Identical validation logic to the embedded variant, but delegates to Spring's JdbcTemplate for external databases. Used when Nacos is configured to use MySQL or PostgreSQL instead of embedded Derby.

Solutions

1. Ensure pageNo >= 1 and pageSize >= 1 in all paginated API requests.
2. Add controller-level validation or form-level defaults to guarantee positive pagination values.
3. Default missing pagination parameters to pageNo=1, pageSize=20.

Example fix

// before
@RequestParam(defaultValue = "0") int pageNo,
@RequestParam(defaultValue = "0") int pageSize
paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);

// after
@RequestParam(defaultValue = "1") int pageNo,
@RequestParam(defaultValue = "20") int pageSize
paginationHelper.fetchPage(countSql, fetchSql, args, pageNo, pageSize, mapper);

// Validate pagination before calling external DB 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 admin auth listing endpoint (users, roles, permissions) calls fetchPage with non-positive pagination values while Nacos is backed by an external database. The guard fires before the count query is sent to the external DB.

Common situations: Frontend pagination initialized at 0; API client omits pagination params defaulting to 0; a REST controller forwards raw query string values without validation; test harness uses 0-based page indexing.

Related errors

• fetchPageLimit error
• pageNo and pageSize must be greater than zero
• fetchPageLimit error
• role '__nacos_anonymous_role__' is reserved by the system
• role 'ROLE_ADMIN' is not permitted to delete!

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

Appendix: source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/persistence/extrnal/AuthExternalPaginationHelperImpl.java:72

     * @param args         query parameters
     * @param pageNo       page number
     * @param pageSize     page size
     * @param rowMapper    {@link RowMapper}
     * @return Paginated data {@code <E>}
     */
    @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 = jdbcTemplate.queryForObject(sqlCountRows, args, Integer.class);
        if (rowCountInt == null) {
            throw new IllegalArgumentException("fetchPageLimit error");
        }
        
        // Compute pages count
        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)