What causes "Paginated queries are missing the necessary parameters:${paramName}" in pagehelper-org/Mybatis-PageHelper?

Supply the missing parameter in the Map/bean under the exact key configured (check the message: it names PARAMS.get(paramName), i.e. the configured key)

pagehelper-org/Mybatis-PageHelper · error · PageException

Paginated queries are missing the necessary parameters

Error message

Paginated queries are missing the necessary parameters:${paramName}

What it means

getParamValue was asked to fetch a required paging parameter (e.g. orderBy, _pageNum, _pageSize, count, reasonable, pageSizeZero) from the parameter object, but no value was found. PageHelper throws PageException naming the missing parameter via the PARAMS mapping. This only fires when required=true, i.e. the parameter was configured as mandatory.

Solutions

Supply the missing parameter in the Map/bean under the exact key configured (check the message: it names PARAMS.get(paramName), i.e. the configured key)
Make the parameter optional in the params config (remove the required flag / adjust params=... string) if the value is genuinely optional
Align configured key names with your DTO/Map keys, or set aliases in the params string (e.g. pageNum=start;pageSize=size)
Log the full parameter object at the call site to confirm which key is absent

Example fix

// before (config requires orderBy)
params=orderBy=orderBy;pageNum=pageNum;pageSize=pageSize
call: startPage(params) with no orderBy key
// after
params.put("orderBy", "id desc");
PageHelper.startPage(params);

Defensive patterns

Strategy: validation

Validate before calling

// configured key from the exception message, e.g. "orderBy"
String key = "orderBy"; // PARAMS.get(paramName) reported by the error
if (params instanceof Map && !((Map<?, ?>) params).containsKey(key)) {
    throw new IllegalArgumentException("required paging param missing: " + key);
}

Try / catch

try {
    PageHelper.startPage(params);
} catch (PageException e) {
    log.error("missing paging parameter: {}", e.getMessage());
    // add the required key or relax the params= configuration
}

Prevention

Keep the params= configuration string and the actual Map/DTO keys in sync
Only mark parameters required in helperDialect params if every call site supplies them
Write a startup/unit test that invokes paging with a representative parameter object

When it happens

Trigger: Params configuration (PageHelper.setParams / helperDialect params=... with required=true, e.g. pageNum=pageNum;pageSize=pageSize;count=count) marks a key required but the caller's Map/bean lacks it; calling orderBy-based paging without supplying orderBy; a renamed/aliased key so getParamValue cannot find it.

Common situations: Setting pageNum=xxx;pageSize=xxx in pagehelper.helperDialect params but passing a bean with differently named fields; removing a request parameter from the frontend while backend config still requires it; copy-pasted params config from a tutorial that expects keys the code never sets.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

     * @param paramName
     * @param required
     * @return
     */
    protected static Object getParamValue(MetaObject paramsObject, String paramName, boolean required) {
        Object value = null;
        if (paramsObject.hasGetter(PARAMS.get(paramName))) {
            value = paramsObject.getValue(PARAMS.get(paramName));
        }
        if (value != null && value.getClass().isArray()) {
            Object[] values = (Object[]) value;
            if (values.length == 0) {
                value = null;
            } else {
                value = values[0];
            }
        }
        if (required && value == null) {
            throw new PageException("Paginated queries are missing the necessary parameters:" + PARAMS.get(paramName));
        }
        return value;
    }

    public static void setParams(String params) {
        if (StringUtil.isNotEmpty(params)) {
            String[] ps = params.split("[;|,|&]");
            for (String s : ps) {
                String[] ss = s.split("[=|:]");
                if (ss.length == 2) {
                    PARAMS.put(ss[0], ss[1]);
                }
            }
        }
    }

}

View on GitHub (pinned to c692616c5b)