alibaba/nacos · error · IllegalArgumentException

pageNo and pageSize must be greater than zero

Error message

pageNo and pageSize must be greater than zero

What it means

Mirror of the embedded helper: ExternalStoragePaginationHelperImpl.checkPageInfo throws IllegalArgumentException when pageNo or pageSize <= 0. This helper backs pagination when Nacos runs against an external (MySQL/PostgreSQL) database via JdbcTemplate.

Source

Thrown at persistence/src/main/java/com/alibaba/nacos/persistence/repository/extrnal/ExternalStoragePaginationHelperImpl.java:116

        List<E> result = jdbcTemplate.query(sqlFetchRows, args, rowMapper);
        for (E item : result) {
            page.getPageItems().add(item);
        }
        return page;
    }
    
    @Override
    public void updateLimit(final String sql, final Object[] args) {
        try {
            jdbcTemplate.update(sql, args);
        } finally {
            EmbeddedStorageContextHolder.cleanAllContext();
        }
    }
    
    private void checkPageInfo(final int pageNo, final int pageSize) {
        if (pageNo <= 0 || pageSize <= 0) {
            throw new IllegalArgumentException("pageNo and pageSize must be greater than zero");
        }
    }
    
    private Page<E> doFetchPage(final String sqlCountRows, final Object[] countAgrs,
        final String sqlFetchRows,
        final Object[] fetchArgs, final int pageNo, final int pageSize, final RowMapper rowMapper) {
        checkPageInfo(pageNo, pageSize);
        // Query the total number of current records
        Integer rowCountInt = null;
        if (null != countAgrs) {
            rowCountInt = jdbcTemplate.queryForObject(sqlCountRows, countAgrs, Integer.class);
        } else {
            rowCountInt = jdbcTemplate.queryForObject(sqlCountRows, Integer.class);
        }
        if (null == rowCountInt) {
            throw new IllegalArgumentException("fetchPageLimit error");
        }
        

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Send pageNo>=1 and pageSize>=1 (1-based paging).
2. Check whether the storage type changed (embedded vs external) which routes to a different helper but with identical validation.
3. Add controller-level validation so bad paging never reaches the persistence layer.

Example fix

// before
request.addParameter("pageNo", "0");
request.addParameter("pageSize", "0");

// after
request.addParameter("pageNo", String.valueOf(Math.max(1, page)));
request.addParameter("pageSize", String.valueOf(size > 0 ? size : 20));

if (pageNo < 1 || pageSize < 1) {
    throw new IllegalArgumentException("pageNo and pageSize must be >= 1");
}

static boolean validPaging(int pageNo, int pageSize) {
    return pageNo >= 1 && pageSize >= 1;
}

When it happens

Trigger: Calling a paginated admin/console API backed by external relational storage with pageNo<=0 or pageSize<=0. The same validation as the embedded path but reached only when the server is configured for MySQL/PostgreSQL persistence.

Common situations: Identical root causes as the embedded variant: 0-based page indexing, missing pageSize default, or negative values forwarded by a client. Surfaces specifically in deployments using nacos.persistence.type=mysql/postgresql.

Related errors

• pageNo and pageSize must be greater than zero
• 20002
• 10000
• 20002
• 10000

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