pagehelper-org/Mybatis-PageHelper · error · IllegalArgumentException

Make sure that the AutoDialect implementation class

Error message

Make sure that the AutoDialect implementation class (${autoDialectClassStr}) for the autoDialectClass configuration exists!

What it means

When the autoDialectClass property is set, PageAutoDialect.initAutoDialectClass resolves the class either from the built-in autoDialect map or via Class.forName. If the class name cannot be found, it throws an IllegalArgumentException telling you the AutoDialect implementation class does not exist.

Solutions

Correct autoDialectClass to a built-in alias (e.g. 'DefaultAutoDialect') or the exact fully-qualified class name.
Add/fix the jar containing the custom AutoDialect implementation on the classpath.
Verify the class implements com.github.pagehelper.dialect.auto.AutoDialect.
Catch IllegalArgumentException at startup and log the configured value for diagnosis.

Example fix

// before
props.setProperty("autoDialectClass", "com.myapp.MyAutoDialct"); // typo
// after
props.setProperty("autoDialectClass", "com.myapp.MyAutoDialect");

Defensive patterns

Strategy: validation

Validate before calling

String v = props.getProperty("autoDialectClass");
if (v != null) {
    try { Class.forName(v); } catch (ClassNotFoundException e) {
        throw new IllegalStateException("autoDialectClass not found: " + v, e);
    }
}

Try / catch

try {
    pluginConfigurer.setProperties(props);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("AutoDialect")) {
        log.error("Bad autoDialectClass={}, falling back to DefaultAutoDialect", props.getProperty("autoDialectClass"), e);
        props.setProperty("autoDialectClass", "DefaultAutoDialect");
        pluginConfigurer.setProperties(props);
    } else { throw e; }
}

Prevention

Use the built-in alias keys from autoDialectMap instead of FQCNs when possible.
Keep the custom AutoDialect class in the deployment artifact; verify with a Class.forName smoke test at startup.
Grep config files for the autoDialectClass value whenever renaming/refactoring the class.
Ensure the class implements the AutoDialect interface of your PageHelper version.

When it happens

Trigger: Configuring autoDialectClass=<name> where <name> is neither a registered alias key in autoDialectMap nor a loadable fully-qualified Class.forName name (typo, missing jar, wrong package).

Common situations: Using a custom AutoDialect without adding its jar to the deployment; misspelling a built-in alias; renaming/refactoring the custom class after upgrading PageHelper so the configured name no longer exists.

Related errors

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

Appendix: source

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

    /**
     * 初始化自定义 AutoDialect
     *
     * @param properties
     */
    private void initAutoDialectClass(Properties properties) {
        String autoDialectClassStr = properties.getProperty("autoDialectClass");
        if (StringUtil.isNotEmpty(autoDialectClassStr)) {
            try {
                Class<? extends AutoDialect> autoDialectClass;
                if (autoDialectMap.containsKey(autoDialectClassStr)) {
                    autoDialectClass = autoDialectMap.get(autoDialectClassStr);
                } else {
                    autoDialectClass = (Class<AutoDialect>) Class.forName(autoDialectClassStr);
                }
                this.autoDialectDelegate = ClassUtil.newInstance(autoDialectClass, properties);
            } catch (ClassNotFoundException e) {
                throw new IllegalArgumentException("Make sure that the AutoDialect implementation class ("
                        + autoDialectClassStr + ") for the autoDialectClass configuration exists!", e);
            } catch (Exception e) {
                throw new RuntimeException(autoDialectClassStr + "Class must provide a constructor without parameters", e);
            }
        } else {
            this.autoDialectDelegate = new DataSourceNegotiationAutoDialect();
        }
    }

    /**
     * 初始化方言别名
     *
     * @param properties
     */
    private void initDialectAlias(Properties properties) {
        String dialectAlias = properties.getProperty("dialectAlias");
        if (StringUtil.isNotEmpty(dialectAlias)) {
            String[] alias = dialectAlias.split(";");

View on GitHub (pinned to c692616c5b)