pagehelper-org/Mybatis-PageHelper · error · PageException

When using PageHelper, the dialect must be an…

Error message

When using PageHelper, the dialect must be an implementation class that implements the ${AbstractHelperDialect} interface!

What it means

instanceDialect resolves the configured dialect string to a Class and requires it to extend AbstractHelperDialect. If the class loads but does not implement that interface, a PageException naming the required canonical class is thrown.

Solutions

1. Make the configured class extend com.github.pagehelper.page.AbstractHelperDialect.
2. Fix helperDialect/dialectAlias to point at a valid built-in dialect (mysql, oracle, postgresql, ...).
3. If using a custom dialect, check its class hierarchy and package against the PageHelper version in use (package moved across major versions).
4. Rebuild/redeploy so the correct class is on the classpath.

Example fix

// before
public class MyDialect implements Dialect { ... }
// after
import com.github.pagehelper.dialect.AbstractHelperDialect;
public class MyDialect extends AbstractHelperDialect { ... }

String clsName = props.getProperty("helperDialect");
if (clsName != null && clsName.contains(".")) {
    Class<?> c = Class.forName(clsName);
    if (!AbstractHelperDialect.class.isAssignableFrom(c)) {
        throw new IllegalStateException(clsName + " must extend AbstractHelperDialect");
    }
}

static boolean isValidDialect(Class<?> c) {
    return c != null && AbstractHelperDialect.class.isAssignableFrom(c);
}

try {
    return PageAutoDialect.instanceDialect(dialectClass, props);
} catch (PageException e) {
    throw new IllegalStateException("Misconfigured dialect '" + dialectClass + "': must extend AbstractHelperDialect", e);
}

When it happens

Trigger: Setting helperDialect (or a dialectAlias value) to a class that exists but is not a subclass of com.github.pagehelper.page.AbstractHelperDialect — e.g. a custom dialect not extending the right base, or a wrong class name pasted into config.

Common situations: Writing a custom pagination dialect that implements the wrong interface or forgets 'extends AbstractHelperDialect'; pointing dialectAlias entries at unrelated classes; copy-pasting a fully-qualified name from another pagination library.

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

• Make sure the Dialect implementation class configured by…
• error initializing helper dialectclass
• Make sure that the AutoDialect implementation class
• order by [ ] has a risk of SQL injection, if you want to…
• count( ) has a risk of SQL injection

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

Appendix: source

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

    }

    /**
     * 初始化 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;
    }

    /**
     * 多数据动态获取时，每次需要初始化，还可以运行时指定具体的实现
     *
     * @param ms
     * @param dialectClass 分页实现，必须是 {@link AbstractHelperDialect} 实现类，可以使用当前类中注册的别名，例如 "mysql", "oracle"
     */
    public void initDelegateDialect(MappedStatement ms, String dialectClass) {
        if (StringUtil.isNotEmpty(dialectClass)) {
            AbstractHelperDialect dialect = urlDialectMap.get(dialectClass);
            if (dialect == null) {

View on GitHub (pinned to c692616c5b)