{"record":{"id":"4d03685a552322d4","repo":"baomidou/mybatis-plus","slug":"error-getting-mapper-instance-cause-s","errorCode":null,"errorMessage":"Error getting mapper instance. Cause: %s","messagePattern":"Error getting mapper instance\\. Cause: (.+?)","errorType":"exception","errorClass":"BindingException","httpStatus":null,"severity":"error","filePath":"mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisMapperRegistry.java","lineNumber":59,"sourceCode":"    public MybatisMapperRegistry(Configuration config) {\n        super(config);\n        this.config = config;\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @Override\n    public <T> T getMapper(Class<T> type, SqlSession sqlSession) {\n        // fix https://github.com/baomidou/mybatis-plus/issues/4247\n        MybatisMapperProxyFactory<T> mapperProxyFactory = (MybatisMapperProxyFactory<T>) knownMappers.get(type);\n        if (mapperProxyFactory == null) {\n            mapperProxyFactory = (MybatisMapperProxyFactory<T>) knownMappers.entrySet().stream()\n                .filter(t -> t.getKey().getName().equals(type.getName())).findFirst().map(Map.Entry::getValue)\n                .orElseThrow(() -> new BindingException(\"Type \" + type + \" is not known to the MybatisPlusMapperRegistry.\"));\n        }\n        try {\n            return mapperProxyFactory.newInstance(sqlSession);\n        } catch (Exception e) {\n            throw new BindingException(\"Error getting mapper instance. Cause: \" + e, e);\n        }\n    }\n\n    @Override\n    public <T> boolean hasMapper(Class<T> type) {\n        return knownMappers.containsKey(type);\n    }\n\n    /**\n     * 清空 Mapper 缓存信息\n     */\n    protected <T> void removeMapper(Class<T> type) {\n        knownMappers.entrySet().stream().filter(t -> t.getKey().getName().equals(type.getName()))\n            .findFirst().ifPresent(t -> knownMappers.remove(t.getKey()));\n    }\n\n    @Override\n    public <T> void addMapper(Class<T> type) {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/baomidou/mybatis-plus/blob/bf67d907478c724120bf76292da54abf9e73c2b3/mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisMapperRegistry.java#L41-L77","documentation":"Wrapped error from MybatisMapperRegistry.getMapper: the mapper proxy factory was found, but mapperProxyFactory.newInstance(sqlSession) threw. This is a facade BindingException where the real cause is attached (and included in the message), so the underlying exception — typically reflection or instantiation failures in proxy creation — must be read from getCause().","triggerScenarios":"sqlSession.getMapper(UserMapper.class) where newInstance fails, e.g. an exception inside MybatisMapperProxy method-interceptor setup or reflective construction of the proxy; any Throwable escaping the factory during JDK dynamic proxy creation.","commonSituations":"A broken MyBatis-Plus interceptor (InnerInterceptor / MybatisPlusInterceptor) failing during proxy or executor creation; incompatible mybatis-plus vs mybatis versions on the classpath causing NoSuchMethodError during proxy init; custom MybatisMapperProxy subclasses misconfigured.","solutions":["Inspect the 'Cause:' portion of the message and e.getCause() — the actual failure (often NoSuchMethodError/ClassNotFoundException) determines the fix.","If the cause is a NoSuchMethodError/NoClassDefFoundError, align mybatis and mybatis-plus versions (check the compatibility matrix; e.g. mybatis-plus 3.5.x pairs with mybatis 3.5.x).","If the cause is inside a custom interceptor, debug or disable that interceptor and retest.","Verify the mapper interface is a plain interface (non-final, visible) resolvable by the classloader that loaded SqlSessionFactory."],"exampleFix":"<!-- before: mismatched versions -->\n<dependency>\n  <groupId>org.mybatis</groupId>\n  <artifactId>mybatis</artifactId>\n  <version>3.4.6</version>\n</dependency>\n<dependency>\n  <groupId>com.baomidou</groupId>\n  <artifactId>mybatis-plus-boot-starter</artifactId>\n  <version>3.5.7</version>\n</dependency>\n\n<!-- after: let the starter manage mybatis -->\n<dependency>\n  <groupId>com.baomidou</groupId>\n  <artifactId>mybatis-plus-boot-starter</artifactId>\n  <version>3.5.7</version>\n</dependency>","handlingStrategy":"try-catch","validationCode":"// precondition: mapper must be registered\nif (!((MybatisMapperRegistry) factory.getConfiguration().getMapperRegistry()).hasMapper(UserMapper.class)) {\n    throw new IllegalStateException(\"UserMapper not registered\");\n}","typeGuard":null,"tryCatchPattern":"try { sqlSession.getMapper(UserMapper.class); } catch (org.apache.ibatis.binding.BindingException e) { throw new IllegalStateException(\"Mapper proxy creation failed: \" + e.getCause(), e.getCause()); } — always unwrap and rethrow the root cause; never retry, since causes are structural (versions, interceptors).","preventionTips":["Keep mybatis and mybatis-plus versions aligned per the compatibility matrix; let the starter manage the mybatis version.","Smoke-test getMapper() for every mapper in a startup health check.","Add new interceptors behind integration tests that obtain and invoke a mapper."],"tags":["mybatis","mybatis-plus","mapper-proxy","dependency-conflict","binding"],"backgroundTag":null,"analyzedSha":"bf67d907478c724120bf76292da54abf9e73c2b3","analyzedAt":"2026-08-14T15:17:09.543Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}