pagehelper-org/Mybatis-PageHelper · error · IllegalArgumentException

Make sure the Dialect implementation class configured by…

Error message

Make sure the Dialect implementation class configured by dialectAlias exists!

What it means

Thrown by PageHelper when the dialectAlias property references a class that cannot be loaded. The plugin tries Class.forName on each configured alias value; a ClassNotFoundException is rethrown as IllegalArgumentException. It means the configured Dialect implementation class does not exist on the classpath or was mistyped.

Solutions

1. Check the dialectAlias value for a typo in the fully-qualified class name
2. Verify the jar containing the Dialect class is on the runtime classpath
3. Use a built-in alias (mysql, oracle, postgresql, etc.) if a custom dialect is not needed
4. Implement the class as an implementation of com.github.pagehelper.Dialect with a no-arg constructor

Example fix

// before
properties.setProperty("dialectAlias", "mydb=com.example.MyDialekt");
// after
properties.setProperty("dialectAlias", "mydb=com.example.MyDialect");

String cls = props.getProperty("dialectAlias").split("=")[1];
try { Class.forName(cls); } catch (ClassNotFoundException e) {
    throw new IllegalStateException("dialectAlias class not on classpath: " + cls);
}

try { pageHelper.setProperties(props); } catch (IllegalArgumentException e) {
    if (e.getCause() instanceof ClassNotFoundException) { /* fix dialectAlias config */ }
}

When it happens

Trigger: Setting helperDialect=custom with dialectAlias=mydb=com.example.MyDialect where the class name is misspelled, the package is wrong, or the jar containing the Dialect implementation is not on the classpath.

Common situations: Typo in fully-qualified class name in MyBatis config; custom dialect jar missing from application classpath or shaded out; refactoring moved/renamed the dialect class without updating plugin properties.

Related errors

• When using PageHelper, the dialect must be an…
• error initializing helper dialectclass
• Make sure that the AutoDialect implementation class
• Created Sql Cache [ ] Error
• When you use the PageHelper pagination plugin, you must set…

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

Appendix: source

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

            String[] alias = dialectAlias.split(";");
            for (int i = 0; i < alias.length; i++) {
                String[] kv = alias[i].split("=");
                if (kv.length != 2) {
                    throw new IllegalArgumentException("dialectAlias parameter misconfigured," +
                            "Please follow alias1=xx.dialectClass; alias2=dialectClass2!");
                }
                for (int j = 0; j < kv.length; j++) {
                    try {
                        //允许配置如 dm=oracle, 直接引用oracle实现
                        if (dialectAliasMap.containsKey(kv[1])) {
                            registerDialectAlias(kv[0], dialectAliasMap.get(kv[1]));
                        } else {
                            Class<? extends Dialect> diallectClass = (Class<? extends Dialect>) Class.forName(kv[1]);
                            //允许覆盖已有的实现
                            registerDialectAlias(kv[0], diallectClass);
                        }
                    } catch (ClassNotFoundException e) {
                        throw new IllegalArgumentException("Make sure the Dialect implementation class configured by dialectAlias exists!", e);
                    }
                }
            }
        }
    }

    public void setProperties(Properties properties) {

        this.properties = properties;
        //初始化自定义AutoDialect
        initAutoDialectClass(properties);
        //使用 sqlserver2012 作为默认分页方式，这种情况在动态数据源时方便使用
        String useSqlserver2012 = properties.getProperty("useSqlserver2012");
        if (StringUtil.isNotEmpty(useSqlserver2012) && Boolean.parseBoolean(useSqlserver2012)) {
            registerDialectAlias("sqlserver", SqlServer2012Dialect.class);
            registerDialectAlias("sqlserver2008", SqlServerDialect.class);
        }
        initDialectAlias(properties);

View on GitHub (pinned to c692616c5b)