{"record":{"id":"f4b0b912e32992a7","repo":"mybatis/mybatis-3","slug":"invalid-bound-statement-not-found-mapperinterf","errorCode":null,"errorMessage":"Invalid bound statement (not found): {mapperInterface}.{methodName}","messagePattern":"Invalid bound statement \\(not found\\): (.+?)\\.(.+?)","errorType":"exception","errorClass":"BindingException","httpStatus":null,"severity":"critical","filePath":"src/main/java/org/apache/ibatis/binding/MapperMethod.java","lineNumber":228,"sourceCode":"        throw new BindingException(\"Parameter '\" + key + \"' not found. Available parameters are \" + keySet());\n      }\n      return super.get(key);\n    }\n\n  }\n\n  public static class SqlCommand {\n\n    private final String name;\n    private final SqlCommandType type;\n\n    public SqlCommand(Configuration configuration, Class<?> mapperInterface, Method method) {\n      final String methodName = method.getName();\n      final Class<?> declaringClass = method.getDeclaringClass();\n      MappedStatement ms = resolveMappedStatement(mapperInterface, methodName, declaringClass, configuration);\n      if (ms == null) {\n        if (method.getAnnotation(Flush.class) == null) {\n          throw new BindingException(\n              \"Invalid bound statement (not found): \" + mapperInterface.getName() + \".\" + methodName);\n        }\n        name = null;\n        type = SqlCommandType.FLUSH;\n      } else {\n        name = ms.getId();\n        type = ms.getSqlCommandType();\n        if (type == SqlCommandType.UNKNOWN) {\n          throw new BindingException(\"Unknown execution method for: \" + name);\n        }\n      }\n    }\n\n    public String getName() {\n      return name;\n    }\n\n    public SqlCommandType getType() {","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/binding/MapperMethod.java#L210-L246","documentation":"The mapper method could not be matched to any MappedStatement in the Configuration. MyBatis looks up statements by fully-qualified name (interface FQN + '.' + method name, walking parent interfaces), and throws this BindingException when nothing is registered. It is the single most common MyBatis startup/first-call error.","triggerScenarios":"No XML <select id=\"...\"> with matching namespace and id; annotation method missing; statement XML file not loaded (not in mapperLocations, not in mybatis-config); interface and XML namespace mismatch; using MyBatis with Spring and the mapper scanned but its XML not on the classpath; method name typo between interface and XML id.","commonSituations":"Maven/Gradle build filtering out XML files from src/main/java; namespace not equal to the interface FQN; forgetting to register the mapper in mybatis-config.xml <mappers>; in mybatis-spring, MapperScan covering a different package than the XML namespace; inner-Interface methods not resolvable through the parent chain.","solutions":["Verify the XML namespace equals the mapper interface fully-qualified name and the statement id equals the method name","Ensure the XML file is actually loaded: add it to mybatis-config.xml <mappers>, set mybatis.mapper-locations in Spring Boot, or annotate the method with @Select/@Insert","Check build packaging: Maven needs <resource> entries to copy *.xml from src/main/java","If using annotations only, confirm the mapper interface is registered (addMapper / @MapperScan) and there are no typos in method names"],"exampleFix":"<!-- before -->\n<mapper namespace=\"com.example.UserMapper\">\n  <select id=\"findUser\" ...>\n<!-- interface: com.example.UserDao#findUser -->\n<!-- after -->\n<mapper namespace=\"com.example.UserDao\">\n  <select id=\"findUser\" ...>","handlingStrategy":"validation","validationCode":"Configuration cfg = sqlSessionFactory.getConfiguration();\nboolean bound = cfg.hasStatement(\"com.example.UserMapper.findUsers\");\nif (!bound) { /* register or fail with clear message */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Namespace must equal the interface FQN; statement id must equal the method name","Verify mapperLocations covers all XML files (Spring: mybatis.mapper-locations=classpath*:mybatis/**/*.xml)","Configure Maven to copy XML living next to sources: <resource><directory>src/main/java</directory><includes><include>**/*.xml</include></includes></resource>","Write a context-loading test that fails fast when a mapper is unbound"],"tags":["mybatis","binding","statement-not-found","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}