{"record":{"id":"423d724ec43bce2c","repo":"pagehelper-org/Mybatis-PageHelper","slug":"failed-to-get-the-boundsql-property-additionalpara","errorCode":null,"errorMessage":"Failed to get the BoundSql property additionalParameters: ${e}","messagePattern":"Failed to get the BoundSql property additionalParameters: (.+?)","errorType":"exception","errorClass":"PageException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/github/pagehelper/util/ExecutorUtil.java","lineNumber":58,"sourceCode":"import java.sql.SQLException;\nimport java.util.List;\nimport java.util.Map;\n\n/**\n * @author liuzenghui\n */\npublic abstract class ExecutorUtil {\n\n    private static Field additionalParametersField;\n\n    private static Field providerMethodArgumentNamesField;\n\n    static {\n        try {\n            additionalParametersField = BoundSql.class.getDeclaredField(\"additionalParameters\");\n            additionalParametersField.setAccessible(true);\n        } catch (NoSuchFieldException e) {\n            throw new PageException(\"Failed to get the BoundSql property additionalParameters: \" + e, e);\n        }\n        try {\n            //兼容低版本\n            providerMethodArgumentNamesField = ProviderSqlSource.class.getDeclaredField(\"providerMethodArgumentNames\");\n            providerMethodArgumentNamesField.setAccessible(true);\n        } catch (NoSuchFieldException ignore) {\n        }\n    }\n\n    /**\n     * 获取 BoundSql 属性值 additionalParameters\n     *\n     * @param boundSql\n     * @return\n     */\n    public static Map<String, Object> getAdditionalParameter(BoundSql boundSql) {\n        try {\n            return (Map<String, Object>) additionalParametersField.get(boundSql);","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/pagehelper-org/Mybatis-PageHelper/blob/c692616c5bc95b41aa779b502f991825c8e5acbc/src/main/java/com/github/pagehelper/util/ExecutorUtil.java#L40-L76","documentation":"ExecutorUtil uses reflection to access the private field BoundSql.additionalParameters, which MyBatis does not expose via a public API in older versions. During class initialization it looks up this field; if the loaded mybatis jar's BoundSql class does not declare it (incompatible/very new or shaded mybatis version), the static initializer throws this PageException and the class fails to load.","triggerScenarios":"Application startup when the ExecutorUtil class is first loaded against a mybatis version whose BoundSql class lacks the 'additionalParameters' field — e.g. a major mybatis upgrade, a shaded/repackaged mybatis, or mismatched pagehelper/mybatis dependency versions.","commonSituations":"Upgrading MyBatis past the version PageHelper was built for; duplicate mybatis jars on the classpath where the wrong one wins; OSGi/shaded deployments hiding the field.","solutions":["Align versions: use a pagehelper release compatible with your mybatis version (check pagehelper's documented mybatis compatibility matrix)","Run mvn dependency:tree (or gradle dependencies) and remove duplicate/conflicting mybatis jars so only one expected version is on the classpath","Downgrade/upgrade mybatis to a version whose BoundSql declares additionalParameters","Upgrade pagehelper to the latest release, which supports newer mybatis APIs","If truly blocked, report to pagehelper issues — newer pagehelper versions avoid this reflection via mybatis's own accessors"],"exampleFix":"// before (pom.xml)\n<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.99</version></dependency>\n<dependency><groupId>com.github.pagehelper</groupId><artifactId>pagehelper</artifactId><version>5.1.4</version></dependency>\n\n// after (compatible pair)\n<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.9</version></dependency>\n<dependency><groupId>com.github.pagehelper</groupId><artifactId>pagehelper</artifactId><version>5.3.2</version></dependency>","handlingStrategy":"try-catch","validationCode":"// Verify compatibility at startup before relying on pagination\ntry {\n    Class.forName(\"com.github.pagehelper.util.ExecutorUtil\");\n} catch (Throwable t) {\n    throw new IllegalStateException(\"PageHelper incompatible with loaded mybatis BoundSql: \" + t, t);\n}","typeGuard":null,"tryCatchPattern":"try (SqlSession session = factory.openSession()) {\n    return mapper.selectPaged(params);\n} catch (PageException e) {\n    if (e.getMessage().contains(\"additionalParameters\")) {\n        throw new IllegalStateException(\"mybatis/pagehelper version mismatch — align versions\", e);\n    }\n    throw e;\n}","preventionTips":["Pin pagehelper and mybatis to a documented compatible version pair in your BOM","Run mvn dependency:tree in CI to detect duplicate mybatis artifacts","Smoke-test pagination at application startup, not only on first page request","Avoid shaded/repackaged mybatis jars"],"tags":["reflection","mybatis","compatibility","classpath"],"backgroundTag":"incompatible-source-type","analyzedSha":"c692616c5bc95b41aa779b502f991825c8e5acbc","analyzedAt":"2026-09-08T03:50:49.192Z","contentChangedAt":"2026-09-08T03:50:49.192Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}