{"record":{"id":"2a6329b204b698ec","repo":"pagehelper-org/Mybatis-PageHelper","slug":"when-you-use-the-pagehelper-pagination-plugin-you","errorCode":null,"errorMessage":"When you use the PageHelper pagination plugin, you must set the helper property","messagePattern":"When you use the PageHelper pagination plugin, you must set the helper property","errorType":"exception","errorClass":"PageException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/github/pagehelper/page/PageAutoDialect.java","lineNumber":198,"sourceCode":"     */\n    public static Class resloveDialectClass(String className) throws Exception {\n        if (dialectAliasMap.containsKey(className.toLowerCase())) {\n            return dialectAliasMap.get(className.toLowerCase());\n        } else {\n            return Class.forName(className);\n        }\n    }\n\n    /**\n     * 初始化 helper\n     *\n     * @param dialectClass\n     * @param properties\n     */\n    public static AbstractHelperDialect instanceDialect(String dialectClass, Properties properties) {\n        AbstractHelperDialect dialect;\n        if (StringUtil.isEmpty(dialectClass)) {\n            throw new PageException(\"When you use the PageHelper pagination plugin, you must set the helper property\");\n        }\n        try {\n            Class sqlDialectClass = resloveDialectClass(dialectClass);\n            if (AbstractHelperDialect.class.isAssignableFrom(sqlDialectClass)) {\n                dialect = (AbstractHelperDialect) sqlDialectClass.newInstance();\n            } else {\n                throw new PageException(\"When using PageHelper, the dialect must be an implementation class that implements the \" + AbstractHelperDialect.class.getCanonicalName() + \" interface!\");\n            }\n        } catch (Exception e) {\n            throw new PageException(\"error initializing helper dialectclass[\" + dialectClass + \"]\" + e.getMessage(), e);\n        }\n        dialect.setProperties(properties);\n        return dialect;\n    }\n\n    /**\n     * 多数据动态获取时，每次需要初始化，还可以运行时指定具体的实现\n     *","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/pagehelper-org/Mybatis-PageHelper/blob/c692616c5bc95b41aa779b502f991825c8e5acbc/src/main/java/com/github/pagehelper/page/PageAutoDialect.java#L180-L216","documentation":"PageAutoDialect.instanceDialect receives the resolved dialect class/key and throws a PageException if it is empty, meaning the PageHelper interceptor was configured without any dialect information (no helperDialect, no autoRuntimeDialect, and no dialectAlias resolution).","triggerScenarios":"Registering the PageHelper interceptor in setProperties with neither helperDialect nor autoRuntimeDialect/autoDialectClass set, so initDelegateDialect ends up calling instanceDialect(null/empty, ...).","commonSituations":"Forgetting the helperDialect property in mybatis-config.xml or Spring property setup; properties not passed to the interceptor (empty Properties object); renaming/refactoring config keys after a version upgrade.","solutions":["Add helperDialect=<dbtype> to the interceptor's properties.","Alternatively set autoRuntimeDialect=true to detect from each datasource's JDBC URL.","Ensure the properties object you build is actually passed to interceptor.setProperties / the plugin configuration.","Check key spelling: helperDialect (case-sensitive) exactly."],"exampleFix":"// before\nPageInterceptor interceptor = new PageInterceptor();\ninterceptor.setProperties(new Properties()); // no dialect\n// after\nProperties props = new Properties();\nprops.setProperty(\"helperDialect\", \"mysql\");\ninterceptor.setProperties(props);","handlingStrategy":"validation","validationCode":"if (StringUtil.isEmpty(props.getProperty(\"helperDialect\"))\n        && StringUtil.isEmpty(props.getProperty(\"autoRuntimeDialect\"))) {\n    throw new IllegalStateException(\"PageHelper needs helperDialect or autoRuntimeDialect\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    interceptor.setProperties(props);\n} catch (PageException e) {\n    log.error(\"PageHelper config incomplete: {}\", e.getMessage());\n    props.setProperty(\"helperDialect\", \"mysql\");\n    interceptor.setProperties(props);\n}","preventionTips":["Make helperDialect a mandatory key in your Spring/mybatis config templates.","Verify the Properties object actually reaches interceptor.setProperties (log its keys at startup).","Watch for key renames across PageHelper version upgrades (helperDialect is case-sensitive).","Fail fast in a startup health check that paginates once."],"tags":["dialect","missing-config","pagehelper","initialization"],"backgroundTag":"missing-required-config-field","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"}