[에러] Failed to determine a suitable driver class — Spring Boot가 DataSource를 못 만들 때

프로젝트에 JPA 의존성을 넣고 실행하면 서버가 뜨기도 전에 이런 화면이 나옵니다.

***************************
APPLICATION FAILED TO START
***************************

Description:

Failed to determine a suitable driver class

Action:

Consider the following:
	If you want an embedded database (H2, HSQL or Derby), please put it on the classpath.
	If you have database settings to be loaded from a particular profile you may need
	to activate it (no profiles are currently active).

메시지가 친절해 보이지만 막막합니다. "드라이버 클래스를 결정하지 못했다"는 말이 드라이버를 안 넣었다는 뜻인지, 주소를 안 썼다는 뜻인지 알기 어렵죠. 로컬에서는 잘 뜨는데 CI나 운영 서버에서만 이렇게 죽는 경우도 흔합니다.

이 글을 다 읽으면 세 가지가 정리됩니다. 첫째, Spring Boot가 DataSource를 만들 때 무엇을 보고 판단하는지 알 수 있습니다. 둘째, 위 메시지의 두 줄짜리 Action이 각각 어떤 상황을 가리키는지 구분할 수 있습니다. 셋째, 상황별로 어떤 설정을 넣어야 하는지 확인할 수 있습니다.

이 글은 Spring Boot 공식 문서를 기준으로 정리했습니다. 버전에 따라 동작이 다를 수 있으니 본인 프로젝트 버전으로 확인해 주세요.

Spring Boot가 DataSource 자동설정에서 갈라지는 분기

Spring Boot는 두 갈래로 판단합니다

이 에러를 이해하려면 자동설정의 분기를 알아야 합니다. 공식 문서가 정한 규칙은 단순합니다.

spring.datasource.url이 있으면 그 URL을 보고 드라이버를 추론합니다. jdbc:mysql://이면 MySQL 드라이버, jdbc:postgresql://이면 PostgreSQL 드라이버를 씁니다. 그래서 driver-class-name은 보통 적지 않아도 됩니다.

spring.datasource.url이 없으면 내장 데이터베이스를 쓰려는 것으로 봅니다. 문서는 H2, HSQL, Derby 중 하나가 classpath에 있어야 자동으로 내장 DB가 설정된다고 밝히고 있습니다.

에러는 이 두 갈래 어디에도 걸리지 못했을 때 납니다. URL도 없고 내장 DB도 없으니 어떤 드라이버를 써야 할지 정할 수 없다는 뜻이죠. 메시지가 "드라이버 클래스를 결정하지 못했다"인 이유입니다.

Spring Boot 공식 문서 — 내장 데이터베이스를 쓸 때는 연결 URL을 지정할 필요가 없다는 설명 (출처: docs.spring.io, 확인일 2026-08-08)

Action 두 줄이 각각 다른 원인입니다

메시지의 Action에는 조언이 두 개 들어 있습니다. 이게 그대로 원인 분류가 됩니다.

원인 1 — 내장 DB 의존성이 없다

가장 흔한 경우입니다. spring-boot-starter-data-jpa만 넣고 DB 드라이버를 안 넣은 상태죠. JPA 스타터에는 데이터베이스 드라이버가 들어 있지 않습니다.

<!-- Maven: 로컬 개발·테스트용 내장 DB -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

// Gradle
runtimeOnly 'com.h2database:h2'

여기서 자주 나는 실수가 scope를 test로 넣는 것입니다. testImplementation이나 <scope>test</scope>로 넣으면 테스트는 통과하는데 bootRun이나 운영 실행에서는 classpath에 없어 같은 에러가 납니다. "테스트는 되는데 실행이 안 된다"면 이걸 먼저 보세요.

원인 2 — 프로퍼티를 못 읽고 있다

메시지 두 번째 줄의 괄호가 힌트를 줍니다. (no profiles are currently active)라고 적혀 있으면 활성 프로필이 없다는 뜻입니다.

DB 설정을 application-local.yml이나 application-prod.yml에만 적어 두고 프로필을 켜지 않으면 그 파일은 읽히지 않습니다.

# 실행 시 프로필 지정
java -jar app.jar --spring.profiles.active=local

# 또는 환경변수
SPRING_PROFILES_ACTIVE=local java -jar app.jar

파일 이름과 위치도 확인 대상입니다. application.yml이 아니라 applicaton.yml처럼 오타가 났거나, src/main/resources가 아닌 곳에 있으면 읽히지 않습니다. YAML 들여쓰기가 깨져 spring.datasource.url이 다른 키 밑으로 들어간 경우도 있습니다.

원인 3 — URL은 있는데 드라이버 JAR이 없다

spring.datasource.url=jdbc:mysql://...을 적었는데 MySQL 드라이버 의존성이 없으면, URL로 추론한 드라이버 클래스를 로드할 수 없습니다.

runtimeOnly 'com.mysql:mysql-connector-j'      // MySQL
runtimeOnly 'org.postgresql:postgresql'        // PostgreSQL
runtimeOnly 'org.mariadb.jdbc:mariadb-java-client'

증상별로 확인할 지점과 조치

상황별로 넣어야 하는 설정

로컬에서 내장 DB로 띄우기

H2를 메모리 모드로 쓸 때 최소 설정입니다.

spring.datasource.url=jdbc:h2:mem:testdb;MODE=MySQL;DB_CLOSE_DELAY=-1
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.h2.console.enabled=true
spring.jpa.hibernate.ddl-auto=create-drop

URL을 아예 안 쓰고 자동설정에 맡기는 방법도 있습니다. 이때는 H2가 classpath에 있어야 하고, 테스트마다 다른 DB를 쓰고 싶다면 이 옵션이 유용합니다.

spring.datasource.generate-unique-name=true

DB_CLOSE_DELAY=-1을 빼면 커넥션이 닫힐 때 메모리 DB가 사라져서 다음 조회에서 테이블을 못 찾습니다. 그 증상은 예전에 정리한 Database "mem:testdb" not found 글과 이어집니다. 지금 다루는 에러는 DataSource를 만들기도 전에 나는 것이고, 그 글의 에러는 DataSource는 만들어졌는데 DB가 사라진 상황이라는 점이 다릅니다.

H2 공식 치트시트의 Database URLs — 파일·메모리·서버 모드 표기와 DB_CLOSE_DELAY (출처: h2database.com, 확인일 2026-08-08)

실제 DB에 붙이기

spring.datasource.url=jdbc:mysql://localhost:3306/app?characterEncoding=UTF-8&serverTimezone=Asia/Seoul
spring.datasource.username=app
spring.datasource.password=${DB_PASSWORD}
# driver-class-name 은 보통 생략 — URL 로 추론됩니다
spring.datasource.hikari.maximum-pool-size=10

Spring Boot는 커넥션 풀로 HikariCP를 먼저 선택합니다. spring-boot-starter-jdbc나 data-jpa를 쓰면 함께 들어오니 별도 설정 없이 동작합니다.

DB 없이 애플리케이션만 띄우기

배치 없는 API 서버를 임시로 확인하거나, DB 연결 없이 컨텍스트만 올려 보고 싶을 때가 있습니다. 이때는 자동설정을 제외합니다.

@SpringBootApplication(exclude = {
        DataSourceAutoConfiguration.class,
        DataSourceTransactionManagerAutoConfiguration.class,
        HibernateJpaAutoConfiguration.class
})
public class MyApplication { }

또는 프로퍼티로도 됩니다.

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

다만 JPA 리포지토리를 쓰는 코드가 남아 있으면 다른 지점에서 빈 생성이 실패합니다. 임시 확인용으로만 쓰시는 편이 좋습니다.

어느 쪽을 고를지

상황	선택
로컬에서 빠르게 돌려 보고 싶다	H2 runtimeOnly + 메모리 URL
테스트만 통과하고 실행이 안 된다	H2 scope를 test → runtime으로
특정 환경에서만 실패한다	그 환경의 활성 프로필과 프로퍼티 파일 확인
URL은 넣었는데 계속 실패한다	해당 DB 드라이버 의존성 추가
DB가 아예 필요 없다	DataSourceAutoConfiguration 제외

확인 순서

• [ ] 에러 메시지의 (no profiles are currently active) 문구가 있는지 본다
• [ ] spring.datasource.url이 실제로 읽히는 파일에 있는지 확인한다
• [ ] 내장 DB 의존성의 scope가 runtime인지 test인지 확인한다
• [ ] URL을 넣었다면 그 DB의 드라이버 의존성이 있는지 확인한다
• [ ] YAML 들여쓰기로 키가 엉키지 않았는지 확인한다
• [ ] 그래도 안 되면 자동설정 보고서로 어떤 설정이 적용됐는지 본다

설정이 실제로 어떻게 읽혔는지 확인할 때 이 두 가지가 편합니다.

# 자동설정 조건 평가 결과를 콘솔에 출력
debug=true

# 활성 프로필과 프로퍼티 소스를 액추에이터로 확인
management.endpoints.web.exposure.include=env,configprops

debug=true로 띄우면 DataSourceAutoConfiguration이 왜 적용되지 않았는지 조건별로 나옵니다. 추측보다 이 로그가 빠릅니다.

다음에 볼 글

DataSource가 만들어진 뒤에 만나는 문제들도 이어서 정리해 두었습니다. H2 메모리 DB가 사라지는 Database "mem:testdb" not found, 그리고 조회 단계에서 나는 LazyInitializationException과 MultipleBagFetchException입니다.

잘못된 내용이나 보충이 필요한 부분이 있으면 댓글로 알려 주시면 반영하겠습니다.

참고한 자료

• Spring Boot Reference — SQL Databases: Embedded Database Support, DataSource Configuration, Connection Pool 선택 순서 (확인일 2026-08-08)
• Spring Boot Reference — Externalized Configuration, Profiles (확인일 2026-08-08)
• H2 Database 공식 문서 — JDBC URL 형식과 메모리 DB 옵션 (확인일 2026-08-08)