What causes "Error getting mapper instance. Cause: %s" in baomidou/mybatis-plus?

Inspect the 'Cause:' portion of the message and e.getCause() — the actual failure (often NoSuchMethodError/ClassNotFoundException) determines the fix.

baomidou/mybatis-plus · error · BindingException

Error getting mapper instance. Cause: %s

Error message

Error getting mapper instance. Cause: %s

What it means

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().

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisMapperRegistry.java:59

    public MybatisMapperRegistry(Configuration config) {
        super(config);
        this.config = config;
    }

    @SuppressWarnings("unchecked")
    @Override
    public <T> T getMapper(Class<T> type, SqlSession sqlSession) {
        // fix https://github.com/baomidou/mybatis-plus/issues/4247
        MybatisMapperProxyFactory<T> mapperProxyFactory = (MybatisMapperProxyFactory<T>) knownMappers.get(type);
        if (mapperProxyFactory == null) {
            mapperProxyFactory = (MybatisMapperProxyFactory<T>) knownMappers.entrySet().stream()
                .filter(t -> t.getKey().getName().equals(type.getName())).findFirst().map(Map.Entry::getValue)
                .orElseThrow(() -> new BindingException("Type " + type + " is not known to the MybatisPlusMapperRegistry."));
        }
        try {
            return mapperProxyFactory.newInstance(sqlSession);
        } catch (Exception e) {
            throw new BindingException("Error getting mapper instance. Cause: " + e, e);
        }
    }

    @Override
    public <T> boolean hasMapper(Class<T> type) {
        return knownMappers.containsKey(type);
    }

    /**
     * 清空 Mapper 缓存信息
     */
    protected <T> void removeMapper(Class<T> type) {
        knownMappers.entrySet().stream().filter(t -> t.getKey().getName().equals(type.getName()))
            .findFirst().ifPresent(t -> knownMappers.remove(t.getKey()));
    }

    @Override
    public <T> void addMapper(Class<T> type) {

View on GitHub (pinned to bf67d90747)

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.

Example fix

<!-- before: mismatched versions -->
<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>3.4.6</version>
</dependency>
<dependency>
  <groupId>com.baomidou</groupId>
  <artifactId>mybatis-plus-boot-starter</artifactId>
  <version>3.5.7</version>
</dependency>

<!-- after: let the starter manage mybatis -->
<dependency>
  <groupId>com.baomidou</groupId>
  <artifactId>mybatis-plus-boot-starter</artifactId>
  <version>3.5.7</version>
</dependency>

Defensive patterns

Strategy: try-catch

Validate before calling

// precondition: mapper must be registered
if (!((MybatisMapperRegistry) factory.getConfiguration().getMapperRegistry()).hasMapper(UserMapper.class)) {
    throw new IllegalStateException("UserMapper not registered");
}

Try / catch

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).

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/4d03685a552322d4. Report an issue: GitHub.