pagehelper-org/Mybatis-PageHelper · error · PageException

When you use the PageHelper pagination plugin, you must set…

Error message

When you use the PageHelper pagination plugin, you must set the helper property

What it means

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).

Solutions

1. Add helperDialect=<dbtype> to the interceptor's properties.
2. Alternatively set autoRuntimeDialect=true to detect from each datasource's JDBC URL.
3. Ensure the properties object you build is actually passed to interceptor.setProperties / the plugin configuration.
4. Check key spelling: helperDialect (case-sensitive) exactly.

Example fix

// before
PageInterceptor interceptor = new PageInterceptor();
interceptor.setProperties(new Properties()); // no dialect
// after
Properties props = new Properties();
props.setProperty("helperDialect", "mysql");
interceptor.setProperties(props);

if (StringUtil.isEmpty(props.getProperty("helperDialect"))
        && StringUtil.isEmpty(props.getProperty("autoRuntimeDialect"))) {
    throw new IllegalStateException("PageHelper needs helperDialect or autoRuntimeDialect");
}

try {
    interceptor.setProperties(props);
} catch (PageException e) {
    log.error("PageHelper config incomplete: {}", e.getMessage());
    props.setProperty("helperDialect", "mysql");
    interceptor.setProperties(props);
}

When it happens

Trigger: Registering the PageHelper interceptor in setProperties with neither helperDialect nor autoRuntimeDialect/autoDialectClass set, so initDelegateDialect ends up calling instanceDialect(null/empty, ...).

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Make sure the Dialect implementation class configured by…
• Created Sql Cache [ ] Error
• When using PageHelper, the dialect must be an…
• error initializing helper dialectclass
• The order by in the original SQL

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

Appendix: source

Thrown at src/main/java/com/github/pagehelper/page/PageAutoDialect.java:198

     */
    public static Class resloveDialectClass(String className) throws Exception {
        if (dialectAliasMap.containsKey(className.toLowerCase())) {
            return dialectAliasMap.get(className.toLowerCase());
        } else {
            return Class.forName(className);
        }
    }

    /**
     * 初始化 helper
     *
     * @param dialectClass
     * @param properties
     */
    public static AbstractHelperDialect instanceDialect(String dialectClass, Properties properties) {
        AbstractHelperDialect dialect;
        if (StringUtil.isEmpty(dialectClass)) {
            throw new PageException("When you use the PageHelper pagination plugin, you must set the helper property");
        }
        try {
            Class sqlDialectClass = resloveDialectClass(dialectClass);
            if (AbstractHelperDialect.class.isAssignableFrom(sqlDialectClass)) {
                dialect = (AbstractHelperDialect) sqlDialectClass.newInstance();
            } else {
                throw new PageException("When using PageHelper, the dialect must be an implementation class that implements the " + AbstractHelperDialect.class.getCanonicalName() + " interface!");
            }
        } catch (Exception e) {
            throw new PageException("error initializing helper dialectclass[" + dialectClass + "]" + e.getMessage(), e);
        }
        dialect.setProperties(properties);
        return dialect;
    }

    /**
     * 多数据动态获取时，每次需要初始化，还可以运行时指定具体的实现
     *

View on GitHub (pinned to c692616c5b)