MyBatis Invalid bound statement (not found) 해결 방법 (원인 7가지 체크리스트)

MyBatis에서 Invalid bound statement (not found) 에러가 발생하는 대표 원인 7가지를 정리했습니다.

namespace/SQL id 불일치, mapper XML 경로 미인식, mapper-scan 설정 오류, build 산출물에 XML 누락, 중복 id/타입 불일치 등 실무에서 자주 터지는 케이스를 체크리스트로 해결해보세요.

 

 

 

MyBatis Invalid bound statement (not found) 에러 해결 (원인 7가지 체크리스트)

MyBatis를 사용하다 보면 아래 에러를 정말 자주 봅니다.

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.selectUser

이 에러의 뜻은 단순합니다.

“MyBatis가 실행하려는 SQL(statement)를 찾지 못했다.”

즉, Mapper 인터페이스 메소드 ↔ Mapper XML의 namespace/id 매핑이 깨졌거나, XML 자체를 못 읽고 있는 상황입니다.

아래 체크리스트를 위에서부터 순서대로 따라가면 대부분 해결됩니다.

---

1. 에러 의미 (왜 못 찾는가?)

예를 들어 에러에 이렇게 찍혔다면:

 

Invalid bound statement (not found): com.example.mapper.UserMapper.selectUser

MyBatis는 다음을 찾으려는 겁니다.

• namespace = com.example.mapper.UserMapper
• id = selectUser

즉 Mapper XML에 이런 형태가 있어야 해요.

 

<mapper namespace="com.example.mapper.UserMapper">
	<select id="selectUser" resultType="..."> SELECT ... </select>
</mapper>

---

2. 가장 흔한 원인 TOP 7

원인 1) namespace와 Mapper 인터페이스 경로 불일치 (1순위)

Mapper XML의 namespace는 보통 **Mapper 인터페이스의 “풀 패키지명”**과 동일해야 합니다.

✅ 올바른 예시

 

<mapper namespace="com.example.mapper.UserMapper">

❌ 잘못된 예시

 

<mapper namespace="UserMapper">
<mapper namespace="com.example.mapper.user.UserMapper"> <!-- 패키지 다름 -->

👉 해결: 에러 메시지에 찍힌 경로 그대로 namespace를 맞추세요.

---

원인 2) id(쿼리명) 오타 / 메소드명 불일치

Mapper 인터페이스:

 

User selectUser(Long id);
Mapper XML:


<select id="selectUsr"> <!-- 오타 -->

이러면 바로 not found 입니다.

✅ 해결 체크

• id와 메소드명이 정확히 같은지 (대소문자 포함)
• 오타/복수형(users)/언더바(_) 등 차이 없는지

---

원인 3) mapper XML이 아예 로딩되지 않음 (경로/설정 문제)

설정에서 mapper XML 위치를 잘못 잡으면 “XML 자체를 못 읽어서” 전부 not found가 납니다.

Spring Boot에서 흔한 설정 예시:

 

mybatis: mapper-locations: classpath:/mapper/**/*.xml

✅ XML 위치가 실제로 아래에 있어야 함:

• src/main/resources/mapper/.../*.xml

💥 흔한 실수:

• mappers 폴더에 두고 mapper로 설정
• classpath*:가 필요한데 classpath:만 씀(멀티 모듈/여러 경로)

---

원인 4) 빌드 산출물에 mapper XML이 포함되지 않음

IDE에서는 되는데, 배포한 jar/war에서만 터지는 경우 1순위 원인입니다.

즉,

• 로컬 실행: OK
• 서버 배포: Invalid bound statement

👉 이 경우 mapper xml이 패키징 결과물에 포함 안 됐을 가능성이 큽니다.

✅ 확인 방법

• jar/war 안에 mapper/*.xml이 존재하는지 확인

✅ 해결 힌트

• Maven/Gradle 리소스 설정 확인
• src/main/resources 아래에 두기

---

원인 5) @MapperScan / @Mapper 설정 누락

Mapper 인터페이스가 스프링 빈으로 등록되지 않으면 매핑이 꼬일 수 있습니다.

✅ 해결 방법 1) 인터페이스에 @Mapper

 

@Mapper public interface UserMapper { ... }

✅ 해결 방법 2) 설정 클래스에 @MapperScan

 

@MapperScan("com.example.mapper")
@SpringBootApplication public class Application { }

---

원인 6) 여러 개 SqlSessionFactory 사용 시 연결 실수 (멀티 DB)

멀티 DB(여러 datasource)를 쓰는 프로젝트에서 자주 터집니다.

예)

• A DB용 SqlSessionFactory는 mapper/a/**/*.xml만 읽음
• 근데 UserMapper는 A 세션팩토리에 붙어있는데 XML은 mapper/b에 있음

👉 그 결과 statement not found.

✅ 해결: DB별로

• mapper-locations 분리
• @MapperScan + sqlSessionFactoryRef 매핑 확인

---

원인 7) 실행 환경(profile)에서 mapper location이 달라짐

dev/prod profile에 따라 설정파일이 다르면

• dev에서는 classpath:/mapper/**/*.xml
• prod에서는 설정 누락/다름

이런 식으로 prod에서만 발생합니다.

✅ 해결:

• application-dev.yml, application-prod.yml에서 mybatis 설정이 동일한지
• 외부 설정 덮어쓰는지 확인

---

✅ 결론: 실무 해결 순서 (이대로 하면 빠름)

1. 에러 메시지에 나온 namespace.id 확인
2. Mapper XML의 namespace가 인터페이스 풀패키지명과 같은지
3. <select id="">가 메소드명과 완전히 일치하는지
4. mybatis.mapper-locations 경로가 XML 실제 위치와 맞는지
5. jar/war 안에 XML이 포함됐는지(서버에서만 터질 때)
6. @MapperScan/@Mapper 등록 여부
7. 멀티 DB면 SqlSessionFactory/mapper-locations 매핑 확인