Cannot load JDBC driver class 해결 방법 (원인 7가지 체크리스트)

Spring Boot에서 Cannot load JDBC driver class 오류가 발생하는 대표 원인을 정리했습니다.

JDBC 드라이버 의존성 누락, driver-class-name 오타, Gradle/Maven scope 설정, jar/war 배포 시 lib 누락, 멀티 모듈/멀티 DB 설정 실수 등 실무에서 자주 터지는 케이스를 체크리스트로 해결해보세요.

 

Cannot load JDBC driver class 해결 방법 (원인 7가지 체크리스트)

Spring Boot에서 DB 연결 설정을 하다 보면 아래 에러를 자주 만나게 됩니다.

Cannot load JDBC driver class 'oracle.jdbc.OracleDriver'
Cannot load JDBC driver class 'com.mysql.cj.jdbc.Driver'
Cannot load JDBC driver class 'org.postgresql.Driver'

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

“JVM이 해당 JDBC Driver 클래스를 클래스패스에서 찾지 못했다.”

즉, 90%는 드라이버 jar가 없거나, 설정이 잘못되어 발생합니다.
아래 체크리스트대로 순서대로 보면 대부분 해결됩니다.

---

1. 에러 의미 (무슨 뜻?)

Spring(또는 HikariCP)이 datasource를 만들면서

1. driver-class-name(또는 URL 기반 자동 추론)을 보고
2. 해당 드라이버 클래스를 Class.forName()으로 로딩하는데
3. 클래스패스에 없으면 실패

→ 그 결과 Cannot load JDBC driver class가 발생합니다.

---

2. 가장 흔한 원인 TOP 7

---

3. 원인 1) JDBC 드라이버 의존성 누락 (1순위)

가장 흔합니다. 드라이버 jar가 아예 없음

Maven (예: MySQL)

<dependency>
  <groupId>com.mysql</groupId>
  <artifactId>mysql-connector-j</artifactId>
</dependency>

 

Maven (예: PostgreSQL)

 

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
</dependency>

Maven (예: Oracle)

오라클 드라이버는 환경에 따라 사내 Nexus/로컬 저장소에서 관리하는 경우가 많습니다.
(프로젝트에서 쓰는 artifactId가 ojdbc8, ojdbc11 등으로 다를 수 있음)

✅ 해결 체크

• pom.xml/build.gradle에 드라이버 dependency가 있는지
• 로컬 repository에 실제 jar가 존재하는지(오라클은 특히)

---

4. 원인 2) driver-class-name 오타/잘못된 드라이버명

설정에 오타가 있으면 당연히 로딩 실패합니다.

예) MySQL 8 드라이버 클래스는 보통 아래입니다.

spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

PostgreSQL:

spring.datasource.driver-class-name=org.postgresql.Driver

Oracle:

spring.datasource.driver-class-name=oracle.jdbc.OracleDriver

✅ 해결 체크

• 에러 메시지에 찍힌 driver 클래스 문자열이 정확한지
• DB 버전에 따라 driver class가 바뀐 건 아닌지 (특히 MySQL 5 → 8)

---

5. 원인 3) scope/provided 때문에 배포물에 빠짐

로컬에서는 잘 되는데 서버에서만 터지면 이 케이스를 의심하세요.

Maven에서 provided로 걸어두면 배포물에 포함되지 않을 수 있습니다.

 

<scope>provided</scope>

✅ 해결

• 드라이버는 보통 compile(runtime 포함) 로 들어가야 함
• provided 사용 시 “서버가 제공한다”는 가정인데, 실제 서버에 없으면 바로 터짐

---

6. 원인 4) jar/war 산출물에 lib 누락(서버에서만 발생)

서버에서만 터진다면 “빌드 산출물 내부에 드라이버 jar가 들어있는지” 확인하세요.

✅ jar 실행(스프링부트 fat jar)이라면:

• BOOT-INF/lib 안에 mysql/postgres/oracle jar가 있어야 함

✅ war 배포라면:

• WEB-INF/lib 안에 드라이버 jar가 있어야 함

👉 없으면 배포물이 잘못 만들어진 겁니다.

---

7. 원인 5) DB 종류 변경했는데 설정이 남아있음

예)

• URL은 postgres인데
• driver-class-name은 mysql로 남아있음

또는

• profile별로 설정이 달라서 dev는 mysql, prod는 oracle 이런데
• prod 설정파일에 드라이버 dependency가 누락된 경우

✅ 해결 체크

• application-dev.yml, application-prod.yml 모두 확인
• 실제 active profile 로그 확인
  • The following profiles are active: prod

---

8. 원인 6) 멀티 DB/멀티 모듈에서 datasource 연결 실수

멀티 datasource를 쓰면 아래 실수가 많습니다.

• A datasource는 oracle driver 필요
• B datasource는 postgres driver 필요
  → 둘 중 하나 드라이버 빠지면 해당 datasource 생성 시점에 터짐

✅ 해결 체크

• datasource별 driver-class-name/URL 분리
• 필요한 드라이버 dependency가 모두 포함되어 있는지

---

9. 원인 7) 클래스패스/캐시 꼬임(IDE/빌드)

“pom/gradle에 넣었는데도 못 찾는다”면 아래 순서로 정리하면 해결되는 경우가 많습니다.

✅ 해결 순서

1. IDE 재시작
2. Clean build
3. Maven/Gradle 리프레시
4. 로컬 .m2/gradle cache 손상 의심 시 재다운로드

Maven:

mvn -U clean package

 

 

Gradle:

./gradlew clean build --refresh-dependencies

---

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

1. 에러에 나온 driver-class-name이 정확한지(오타/DB 버전)
2. pom/gradle에 JDBC 드라이버 dependency가 있는지
3. profile(dev/prod)에서 설정이 달라진 건 아닌지
4. 서버에서만 터지면 jar/war 안에 드라이버 jar 포함 여부 확인
5. provided/scope 설정 때문에 빠진 건 아닌지
6. 멀티 datasource면 각각 드라이버 포함 여부 확인
7. 마지막으로 clean build + 캐시 정리