pagehelper-org/Mybatis-PageHelper · error · IllegalArgumentException

dialectAlias parameter misconfigured,Please follow…

Error message

dialectAlias parameter misconfigured,Please follow alias1=xx.dialectClass; alias2=dialectClass2!

What it means

initDialectAlias parses the dialectAlias property, expected as semicolon-separated alias=class pairs. If any segment does not split into exactly two '='-separated parts, an IllegalArgumentException with the required format is thrown at interceptor initialization.

Solutions

Format the value strictly as alias1=fqcn;alias2=fqcn with semicolons between pairs and exactly one '=' per pair.
Remove trailing semicolons and stray whitespace/quotes from the property value.
Verify in code before init: split on ';' then on '=' and assert each segment has length 2.
If you only need one database, drop dialectAlias and use helperDialect instead.

Example fix

// before
dialectAlias=oracle=com.github.pagehelper.dialect.helper.OracleDb;dm=oracle,
// after (comma removed, one pair per alias)
dialectAlias=oracle=com.github.pagehelper.dialect.helper.OracleDb;dm=oracle

Defensive patterns

Strategy: validation

Validate before calling

String dialectAlias = props.getProperty("dialectAlias");
if (dialectAlias != null) {
    for (String pair : dialectAlias.split(";")) {
        if (pair.split("=").length != 2 || pair.isEmpty()) {
            throw new IllegalStateException("Bad dialectAlias segment: [" + pair + "]");
        }
    }
}

Try / catch

try {
    pluginConfigurer.setProperties(props);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("dialectAlias parameter misconfigured")) {
        log.error("Invalid dialectAlias value: [{}]", props.getProperty("dialectAlias"), e);
    }
    throw e;
}

Prevention

Keep the format exactly alias=fqcn pairs joined by ';' — one '=' per pair, no trailing semicolon.
Trim whitespace and avoid quoting the property value.
Centralize the dialectAlias string in one config constant and unit-test parsing it.
If aliasing to a built-in dialect (dm=oracle) verify the alias key exists in your PageHelper version.

When it happens

Trigger: Setting dialectAlias to a malformed value, e.g. missing '=' ("oracle=com...;foo"), extra '=' ("oracle=com.x.Y=Z"), trailing semicolon producing an empty segment, or whitespace/typo like 'oralce=com...' with a stray comma.

Common situations: Copy-pasting dialectAlias config from docs with mixed separators (comma instead of semicolon); leaving a trailing ';'; quoting the whole value so quotes become part of the tokens; case where kv.length != 2 because the class name itself contains '='.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

            }
        } 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(";");
            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);
                    }
                }
            }
        }

View on GitHub (pinned to c692616c5b)