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

Thrown by EmbeddedPaginationHelperImpl.checkPageInfo (private) when pageNo or pageSize is <= 0, as an IllegalArgumentException before any query runs. This helper backs pagination for the embedded Derby storage.

Source

Thrown at persistence/src/main/java/com/alibaba/nacos/persistence/repository/embedded/EmbeddedPaginationHelperImpl.java:118

        return fetchPageLimit(countMapperResult.getSql(),
            countMapperResult.getParamList().toArray(),
            mapperResult.getSql(), mapperResult.getParamList().toArray(), pageNo, pageSize,
            rowMapper);
    }
    
    @Override
    public void updateLimit(final String sql, final Object[] args) {
        EmbeddedStorageContextHolder.addSqlContext(sql, args);
        try {
            databaseOperate.update(EmbeddedStorageContextHolder.getCurrentSqlContext());
        } 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 = databaseOperate.queryOne(sqlCountRows, countAgrs, Integer.class);
        } else {
            rowCountInt = databaseOperate.queryOne(sqlCountRows, Integer.class);
        }
        if (rowCountInt == null) {
            throw new IllegalArgumentException("fetchPageLimit error");
        }
        

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure pageNo and pageSize are both >= 1 in the request (Nacos uses 1-based page numbers).
2. If the error comes from an internal caller, trace which API forwarded the zero/negative value and fix the default there.
3. Validate pagination inputs at the controller boundary before delegating to the persistence helper.

Example fix

// before
int pageNo = 0;     // wrong: 0-based
int pageSize = 0;

// after
int pageNo = Math.max(1, requestedPage);
int pageSize = requestedSize > 0 ? requestedSize : defaultPageSize;

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 (config history, namespace list, etc.) backed by embedded storage with pageNo=0, pageNo<0, pageSize=0, or pageSize<0. Also triggered by internal services that forward zero/negative page parameters from a request.

Common situations: Clients using 0-based page indexing while Nacos expects 1-based; defaulting pageSize to 0 when the request omits it; off-by-one bugs in pagination parameter forwarding.

Related errors

• pageNo and pageSize must be greater than zero
• Unsupported SQL: %s. Nacos only support DML and some DDL SQL
• 20002
• 10000
• 20002

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