mybatis/mybatis-3 · error · BindingException

Type {type} is not known to the MapperRegistry.

Error message

Type {type} is not known to the MapperRegistry.

What it means

MapperRegistry.getMapper() only returns proxies for interfaces that were explicitly registered (via addMapper, <mapper class=...>, package scan, or @MapperScan). Asking for an unregistered type throws this BindingException, listing the offending class.

Source

Thrown at src/main/java/org/apache/ibatis/binding/MapperRegistry.java:47

/**
 * @author Clinton Begin
 * @author Eduardo Macarron
 * @author Lasse Voss
 */
public class MapperRegistry {

  private final Configuration config;
  private final Map<Class<?>, MapperProxyFactory<?>> knownMappers = new ConcurrentHashMap<>();

  public MapperRegistry(Configuration config) {
    this.config = config;
  }

  @SuppressWarnings("unchecked")
  public <T> T getMapper(Class<T> type, SqlSession sqlSession) {
    final MapperProxyFactory<T> mapperProxyFactory = (MapperProxyFactory<T>) knownMappers.get(type);
    if (mapperProxyFactory == null) {
      throw new BindingException("Type " + type + " is not known to the MapperRegistry.");
    }
    try {
      return mapperProxyFactory.newInstance(sqlSession);
    } catch (Exception e) {
      throw new BindingException("Error getting mapper instance. Cause: " + e, e);
    }
  }

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

  public <T> void addMapper(Class<T> type) {
    if (type.isInterface()) {
      if (hasMapper(type)) {
        throw new BindingException("Type " + type + " is already known to the MapperRegistry.");
      }
      boolean loadCompleted = false;

View on GitHub (pinned to 008069adb1)

Solutions

1. Register the interface: <mapper class="com.example.FooMapper"/> or <package name="com.example"/> in mybatis-config.xml, or configuration.addMapper(FooMapper.class)
2. In Spring Boot, add @Mapper to the interface or extend the @MapperScan basePackages to include it
3. Verify with session.getConfiguration().getMapperRegistry().hasMapper(FooMapper.class) before calling getMapper

Example fix

// before
SqlSession session = factory.openSession();
FooMapper m = session.getMapper(FooMapper.class); // not registered
// after
factory.getConfiguration().addMapper(FooMapper.class);
FooMapper m = session.getMapper(FooMapper.class);

if (!sqlSessionFactory.getConfiguration().getMapperRegistry().hasMapper(FooMapper.class)) {
  sqlSessionFactory.getConfiguration().addMapper(FooMapper.class);
}
FooMapper m = session.getMapper(FooMapper.class);

When it happens

Trigger: session.getMapper(UnregisteredMapper.class) without prior registration; mapper package not covered by mybatis-config <package name=.../>; in Spring Boot, the interface outside the @MapperScan basePackages and not annotated with @Mapper.

Common situations: Newly added mapper interfaces forgotten in the scan config; XML registered but interface not (XML-only registration does not register the interface class); typo in the @MapperScan package; unit tests constructing a SqlSessionFactory without loading the mapper.

Related errors

• Invalid bound statement (not found): {mapperInterface}.{meth
• Type {type} is already known to the MapperRegistry.
• Unknown execution method for: {name}
• Mapper method '{name}' attempted to return null from a metho
• Mapper method '{name}' has an unsupported return type: {retu

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/0ff5bb109db925cf. Report an issue: GitHub.