apache/incubator-seata · warning · IllegalArgumentException

"pageNum range not in [" + MIN_PAGE_NUM + "-" + MAX_PAGE_NUM

Error message

"pageNum range not in [" + MIN_PAGE_NUM + "-" + MAX_PAGE_NUM + "]"

What it means

PageUtil.checkParam enforces server-side pagination limits for Seata's paged queries (console/session/lock list endpoints). Page numbers must be within [MIN_PAGE_NUM=1, MAX_PAGE_NUM=999]; a pageNum of 0 or below, or above 999, throws IllegalArgumentException with the allowed range in the message.

Source

Thrown at common/src/main/java/org/apache/seata/common/util/PageUtil.java:93

    private static final String ORACLE_PAGE_TEMPLATE = "select * from ( select ROWNUM rn, temp.* from ("
            + SOURCE_SQL_PLACE_HOLD + ") temp ) where rn between " + START_PLACE_HOLD + " and " + END_PLACE_HOLD;

    /**
     * The constant SQLSERVER_PAGE_TEMPLATE. Currently, it only works for order-by condition of "ORDER BY gmt_create desc"
     */
    private static final String SQLSERVER_PAGE_TEMPLATE =
            "select * from (select temp.*, ROW_NUMBER() OVER(ORDER BY gmt_create desc) AS rowId from ("
                    + SOURCE_SQL_PLACE_HOLD + ") temp ) t where t.rowId between " + START_PLACE_HOLD + " and "
                    + END_PLACE_HOLD;
    /**
     * check page parm
     *
     * @param pageNum the page num
     * @param pageSize the page size
     */
    public static void checkParam(int pageNum, int pageSize) {
        if (!(pageNum >= MIN_PAGE_NUM && pageNum <= MAX_PAGE_NUM)) {
            throw new IllegalArgumentException("pageNum range not in [" + MIN_PAGE_NUM + "-" + MAX_PAGE_NUM + "]");
        }
        if (!(pageSize >= MIN_PAGE_SIZE && pageSize <= MAX_PAGE_SIZE)) {
            throw new IllegalArgumentException("pageSize range not in [" + MIN_PAGE_SIZE + "-" + MAX_PAGE_SIZE + "]");
        }
    }

    /**
     * get pagesql
     *
     * @param sourceSql the source sql
     * @param dbType the db type
     * @param pageNum the page num
     * @param pageSize the page size
     * @return the page sql
     */
    public static String pageSql(String sourceSql, String dbType, int pageNum, int pageSize) {
        switch (dbType) {
            case "mysql":

View on GitHub (pinned to e01f97c6db)

Solutions

1. Send pageNum in [1,999]; convert zero-based UI indices with pageNum = index + 1
2. Clamp pageNum before calling: Math.min(Math.max(pageNum, 1), 999)
3. Return an empty result instead of querying when the requested page exceeds total pages

Example fix

// before
PageUtil.checkParam(0, 10); // throws

// after
int safe = Math.min(Math.max(requestedPage, PageUtil.MIN_PAGE_NUM), PageUtil.MAX_PAGE_NUM);
PageUtil.checkParam(safe, 10);

int pageNum = Math.min(Math.max(requestedPage, PageUtil.MIN_PAGE_NUM), PageUtil.MAX_PAGE_NUM);
PageUtil.checkParam(pageNum, pageSize);

try { PageUtil.checkParam(p, s); } catch (IllegalArgumentException e) { return ResponseEntity.badRequest().body(e.getMessage()); }

When it happens

Trigger: Calling PageUtil.checkParam(pageNum, pageSize) — directly or via console list APIs — with pageNum=0 (common when a caller computes pageNum from an offset incorrectly) or pageNum > 999.

Common situations: Frontend sending page=0 because it uses zero-based paging while the API is one-based; a UI letting users jump to an arbitrarily high page; automated clients looping past page 999.

Related errors

• "pageSize range not in [" + MIN_PAGE_SIZE + "-" + MAX_PAGE_S
• Two or more start states, ${target} and ${definitions.StartS
• URL must not be null or blank
• ip and port string cannot be empty!
• "PageUtil not support this dbType:" + dbType

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/c06cfffcf9a4bb9a. Report an issue: GitHub.