{"record":{"id":"0ff5bb109db925cf","repo":"mybatis/mybatis-3","slug":"type-type-is-not-known-to-the-mapperregistry","errorCode":null,"errorMessage":"Type {type} is not known to the MapperRegistry.","messagePattern":"Type (.+?) is not known to the MapperRegistry\\.","errorType":"exception","errorClass":"BindingException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/binding/MapperRegistry.java","lineNumber":47,"sourceCode":"/**\n * @author Clinton Begin\n * @author Eduardo Macarron\n * @author Lasse Voss\n */\npublic class MapperRegistry {\n\n  private final Configuration config;\n  private final Map<Class<?>, MapperProxyFactory<?>> knownMappers = new ConcurrentHashMap<>();\n\n  public MapperRegistry(Configuration config) {\n    this.config = config;\n  }\n\n  @SuppressWarnings(\"unchecked\")\n  public <T> T getMapper(Class<T> type, SqlSession sqlSession) {\n    final MapperProxyFactory<T> mapperProxyFactory = (MapperProxyFactory<T>) knownMappers.get(type);\n    if (mapperProxyFactory == null) {\n      throw new BindingException(\"Type \" + type + \" is not known to the MapperRegistry.\");\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  public <T> boolean hasMapper(Class<T> type) {\n    return knownMappers.containsKey(type);\n  }\n\n  public <T> void addMapper(Class<T> type) {\n    if (type.isInterface()) {\n      if (hasMapper(type)) {\n        throw new BindingException(\"Type \" + type + \" is already known to the MapperRegistry.\");\n      }\n      boolean loadCompleted = false;","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/binding/MapperRegistry.java#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the interface: <mapper class=\"com.example.FooMapper\"/> or <package name=\"com.example\"/> in mybatis-config.xml, or configuration.addMapper(FooMapper.class)","In Spring Boot, add @Mapper to the interface or extend the @MapperScan basePackages to include it","Verify with session.getConfiguration().getMapperRegistry().hasMapper(FooMapper.class) before calling getMapper"],"exampleFix":"// before\nSqlSession session = factory.openSession();\nFooMapper m = session.getMapper(FooMapper.class); // not registered\n// after\nfactory.getConfiguration().addMapper(FooMapper.class);\nFooMapper m = session.getMapper(FooMapper.class);","handlingStrategy":"validation","validationCode":"if (!sqlSessionFactory.getConfiguration().getMapperRegistry().hasMapper(FooMapper.class)) {\n  sqlSessionFactory.getConfiguration().addMapper(FooMapper.class);\n}\nFooMapper m = session.getMapper(FooMapper.class);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Register mappers via one mechanism: <package> scan, @MapperScan, or addMapper","In Spring Boot, annotate interfaces with @Mapper and verify MapperScan basePackages"],"tags":["mybatis","binding","mapper-registry","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}