{"record":{"id":"c6751a371e28febc","repo":"pagehelper-org/Mybatis-PageHelper","slug":"paginated-queries-are-missing-the-necessary-parame","errorCode":null,"errorMessage":"Paginated queries are missing the necessary parameters:${paramName}","messagePattern":"Paginated queries are missing the necessary parameters:(.+?)","errorType":"exception","errorClass":"PageException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/github/pagehelper/util/PageObjectUtil.java","lineNumber":173,"sourceCode":"     * @param paramName\n     * @param required\n     * @return\n     */\n    protected static Object getParamValue(MetaObject paramsObject, String paramName, boolean required) {\n        Object value = null;\n        if (paramsObject.hasGetter(PARAMS.get(paramName))) {\n            value = paramsObject.getValue(PARAMS.get(paramName));\n        }\n        if (value != null && value.getClass().isArray()) {\n            Object[] values = (Object[]) value;\n            if (values.length == 0) {\n                value = null;\n            } else {\n                value = values[0];\n            }\n        }\n        if (required && value == null) {\n            throw new PageException(\"Paginated queries are missing the necessary parameters:\" + PARAMS.get(paramName));\n        }\n        return value;\n    }\n\n    public static void setParams(String params) {\n        if (StringUtil.isNotEmpty(params)) {\n            String[] ps = params.split(\"[;|,|&]\");\n            for (String s : ps) {\n                String[] ss = s.split(\"[=|:]\");\n                if (ss.length == 2) {\n                    PARAMS.put(ss[0], ss[1]);\n                }\n            }\n        }\n    }\n\n}\n","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/pagehelper-org/Mybatis-PageHelper/blob/c692616c5bc95b41aa779b502f991825c8e5acbc/src/main/java/com/github/pagehelper/util/PageObjectUtil.java#L155-L191","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (config requires orderBy)\nparams=orderBy=orderBy;pageNum=pageNum;pageSize=pageSize\ncall: startPage(params) with no orderBy key\n// after\nparams.put(\"orderBy\", \"id desc\");\nPageHelper.startPage(params);","handlingStrategy":"validation","validationCode":"// configured key from the exception message, e.g. \"orderBy\"\nString key = \"orderBy\"; // PARAMS.get(paramName) reported by the error\nif (params instanceof Map && !((Map<?, ?>) params).containsKey(key)) {\n    throw new IllegalArgumentException(\"required paging param missing: \" + key);\n}","typeGuard":null,"tryCatchPattern":"try {\n    PageHelper.startPage(params);\n} catch (PageException e) {\n    log.error(\"missing paging parameter: {}\", e.getMessage());\n    // add the required key or relax the params= configuration\n}","preventionTips":["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"],"tags":["pagination","missing-parameter","config","mybatis","pagehelper"],"backgroundTag":"missing-required-argument","analyzedSha":"c692616c5bc95b41aa779b502f991825c8e5acbc","analyzedAt":"2026-09-08T03:50:49.192Z","contentChangedAt":"2026-09-08T03:50:49.192Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}