What causes "The pagination query parameter failed to be processed!" in pagehelper-org/Mybatis-PageHelper?

Pass a supported parameter type: a java.util.Map with pageNum/pageSize keys, an IPage implementation, or a plain bean with pageNum/pageSize getters

pagehelper-org/Mybatis-PageHelper · error · PageException

The pagination query parameter failed to be processed!

Error message

The pagination query parameter failed to be processed!

What it means

PageHelper tried to wrap the supplied pagination parameter into a MetaObject for reflective property access, but the resulting MetaObject came back null. This means the params object type could not be processed (neither Map, IPage, nor a reflectively accessible bean). The library throws PageException because it cannot read pageNum/pageSize/orderBy properties from it.

Solutions

Pass a supported parameter type: a java.util.Map with pageNum/pageSize keys, an IPage implementation, or a plain bean with pageNum/pageSize getters
Inspect the object actually passed at the call site and log its class to find the unsupported type
Convert exotic types to a Map before paging (e.g. objectMapper.convertValue(dto, Map.class))
Update PageHelper if the type used to work — check the version's supported parameter types in PageObjectUtil

Example fix

// before
PageHelper.startPage(someString);
// after
Map<String, Object> params = new HashMap<>();
params.put("pageNum", pageNum);
params.put("pageSize", pageSize);
PageHelper.startPage(params);

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(params instanceof Map || params instanceof IPage)) {
    throw new IllegalArgumentException(
        "paging params must be Map, IPage, or a bean, got: "
        + (params == null ? "null" : params.getClass().getName()));
}

Type guard

boolean isSupportedPagingParam(Object p) {
    return p instanceof Map || p instanceof IPage
        || (p != null && !p.getClass().isPrimitive()
            && !p.getClass().isArray()
            && !(p instanceof String));
}

Try / catch

try {
    PageHelper.startPage(params);
} catch (PageException e) {
    log.error("unsupported paging param type {}: {}",
        params == null ? null : params.getClass(), e.getMessage());
}

Prevention

Only pass Map, IPage, or POJOs with getters to the paging API
Never pass Strings, wrappers, or arrays as paging parameter objects
Convert request DTOs to Maps via Jackson if reflection access is uncertain

When it happens

Trigger: Passing an exotic object (primitive wrapper, String, array, or type with no accessible properties) as the paging parameter object to startPage(params); a custom parameter wrapper whose type is not supported by MetaObjectUtil.forObject; calling getPageFromObject directly with an unsupported type.

Common situations: Passing a JSON string or Integer instead of a Map/bean to the paging overload; after upgrading PageHelper, previously tolerated parameter types now fail MetaObject creation; using a custom Page-like class that the library does not recognize and that reflection cannot expose.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of pagehelper-org/Mybatis-PageHelper@c692616c5b (2026-09-08). Data as JSON: /api/errors/6dd9b03658058326. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/com/github/pagehelper/util/PageObjectUtil.java:104

                    page.setOrderByOnly(true);
                }
            }
            return page;
        }
        int pageNum;
        int pageSize;
        MetaObject paramsObject = null;
        if (hasRequest && requestClass.isAssignableFrom(params.getClass())) {
            try {
                paramsObject = MetaObjectUtil.forObject(getParameterMap.invoke(params, new Object[]{}));
            } catch (Exception e) {
                //忽略
            }
        } else {
            paramsObject = MetaObjectUtil.forObject(params);
        }
        if (paramsObject == null) {
            throw new PageException("The pagination query parameter failed to be processed!");
        }
        Object orderBy = getParamValue(paramsObject, "orderBy", false);
        boolean hasOrderBy = false;
        if (orderBy != null && orderBy.toString().length() > 0) {
            hasOrderBy = true;
        }
        try {
            Object _pageNum = getParamValue(paramsObject, "pageNum", required);
            Object _pageSize = getParamValue(paramsObject, "pageSize", required);
            if (_pageNum == null || _pageSize == null) {
                if(hasOrderBy){
                    Page page = new Page();
                    page.setOrderBy(orderBy.toString());
                    page.setOrderByOnly(true);
                    return page;
                }
                return null;
            }

View on GitHub (pinned to c692616c5b)