[MyBatis] Invalid bound statement (not found) 에러 완벽 해결법

Spring Boot와 MyBatis를 연동할 때 개발자를 가장 당혹스럽게 만드는 에러가 바로 BindingException: Invalid bound statement (not found)입니다. 프로젝트 빌드는 잘 되었는데, 막상 DB를 호출하는 시점에 발생하는 이 에러! 오늘은 가장 빈번한 원인 4가지와 확실한 해결책을 정리해 드립니다.

---

1. 에러의 핵심 원인: "연결 고리가 끊겼다"

이 에러는 쉽게 말해 "자바 인터페이스(Mapper)와 실행할 SQL이 담긴 XML 파일이 서로 매칭되지 않을 때" 발생합니다. 스프링이 "이 메서드를 실행하려는데 실행할 쿼리가 어디 있지?"라며 길을 잃은 상태라고 보시면 됩니다.

---

2. 해결 방법 1: namespace와 인터페이스 경로 일치 (가장 중요!)

가장 흔한 실수입니다. XML 파일 상단의 namespace 값은 반드시 Mapper 인터페이스의 전체 경로(Full Package Name)와 토씨 하나 틀리지 않고 일치해야 합니다.

✅ 체크포인트:

• 잘못된 예: <mapper namespace="UserMapper">
• 올바른 예: <mapper namespace="com.sunny.project.mapper.UserMapper">

---

3. 해결 방법 2: 메서드 ID와 XML id 일치 여부

Mapper 인터페이스에 정의한 메서드 이름과 XML 파일 안의 SQL 태그 id가 정확히 일치하는지 확인하세요.

// UserMapper.java (인터페이스)
public interface UserMapper {
    User selectUserInfo(String userId); // 메서드명: selectUserInfo
}

<select id="selectUserInfo" resultType="com.sunny.project.model.User">
    SELECT * FROM users WHERE user_id = #{userId}
</select>

• 대소문자 오타가 없는지, 마침표나 공백이 들어가지 않았는지 꼭 확인해야 합니다.

---

4. 해결 방법 3: application.properties 경로 설정

스프링 부트가 XML 파일들을 어디서 찾아야 할지 모르는 경우입니다. application.properties (또는 .yml) 파일의 설정을 점검하세요.

# application.properties
mybatis.mapper-locations=classpath:mappers/**/*.xml

• 주의: src/main/resources 하위 경로와 실제 XML 파일이 위치한 경로가 위 설정과 일치하는지 확인하세요. (예: resources/mappers/UserMapper.xml)

---

5. 해결 방법 4: 빌드(Build) 결과 확인 (IntelliJ/Eclipse)

간혹 코드는 맞는데 빌드 도구의 문제로 XML 파일이 target 혹은 out 폴더(배포 경로)로 복사되지 않는 경우가 있습니다.

1. 프로젝트를 Clean 후 다시 Build 해보세요.
2. src/main/java 패키지 안에 XML을 두었다면, 빌드 시 XML이 누락될 수 있습니다. 가급적 XML은 src/main/resources 하위로 옮기는 것을 권장합니다.

---

마무리하며

Invalid bound statement (not found) 에러는 결국 '이름표 매칭'의 문제입니다.

1. Namespace 경로가 정확한가?
2. Method ID가 일치하는가?
3. XML 파일 위치를 스프링이 알고 있는가?

이 세 가지만 확인하면 99% 해결됩니다. 오늘 포스팅이 여러분의 '칼퇴'에 도움이 되었기를 바랍니다!

---