Spring Boot ‘Failed to configure a DataSource’ 오류 해결 — Batch + MongoDB 조합에서 체크할 6가지

검증 환경

본 절은 원문 사례·문서에 등장한 버전/도구를 정리한 것이다. 별도 실험실 재현이 명시되지 않은 항목은 일반화하지 않는다.

• 본문에 명시된 오류 메시지·프레임워크 버전을 기준으로 원인을 추적했다.
• 문서 정리일: 2026-09-02
• OS/CI 세부 값은 프로젝트마다 다르므로, 적용 전 로컬에서 동일 오류 메시지를 재확인한다.

1. 문제 정의

Spring Boot Batch 예제를 MongoDB와 함께 작성하고 mongod 서버를 먼저 실행한 뒤에도 애플리케이션이 다음 에러로 종료되는 상황입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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

Description:
Failed to configure a DataSource: 'url' attribute is not specified
and no embedded datasource could be configured.

Reason: 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).

실제로 mongod는 정상적으로 실행 중인데도 같은 에러가 발생하는데, 여기서 핵심은 MongoDB 서버가 살아 있는지와 무관하게 스프링 부트가 “관계형 DataSource"를 만드려다 실패한다는 점입니다.

소스 레퍼런스 설정 예시:

1
2

# Mongo database URI. Cannot be set with host, port and credentials.
spring.data.mongodb.uri=mongodb://localhost/test

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-batch</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-mongodb</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

증상 fingerprint

2. 빠른 진단 체크리스트

에러 로그의 Reason: Failed to determine a suitable driver class라는 문장이 곧 핵심 단서입니다. 아래 순서대로 점검하세요. 체크가 완료될 때마다 그 원인을 배제하고 다음 단계로 넘어갑니다.

• 2-1. spring-boot-starter-data-jpa 또는 spring-boot-starter-batch가 pom.xml에 있는지 확인 이 스타터들은 DataSourceAutoConfiguration을 트리거합니다.
• 2-2. application.properties에 spring.datasource.url이 존재하는지 확인 url이 없으면 부트는 내장 DB(H2/HSQL/Derby)를 뒤지고, 그것도 없으면 실패합니다.
• 2-3. (RDBMS 사용 시) 드라이버 클래스명 철자와 표기법 확인 스프링 부트 2.x에서는 spring.datasource.driver-class-name(하이픈 표기)이 맞습니다.
• 2-4. (MongoDB만 사용) DataSource 자동 설정을 정말 필요한지 판단 필요 없다면 자동 설정을 제외하는 방향으로 갑니다.
• 2-5. 프로파일 활성화 여부 확인 데이터소스 설정이 특정 profile에만 있을 수 있으므로 현재 활성 프로파일을 점검합니다.

3. 원인 후보별 확인 방법

위 표의 “확인 명령/방법” 중 코드로 확인해야 하는 항목은 mvn -q dependency:tree 로 실제 의존성을 확인할 것을 권장합니다. 표의 진단 기준은 환경에 따라 다를 수 있는 일반적인 점검 기준입니다.

4. 해결 방법

4-1. MongoDB만 쓰는 경우 — DataSource 자동 설정 제외 (권장)

MongoDB 단독 프로젝트에는 관계형 DataSource가 애초에 필요 없습니다. 스프링 부트의 JDBC/DataSource 자동 설정을 끄고, Mongo 구성만 남깁니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

package com.example.batch;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.mongodb.repository.config.EnableMongoRepositories;

@Configuration
@EnableAutoConfiguration(exclude = {
    DataSourceAutoConfiguration.class,
    DataSourceTransactionManagerAutoConfiguration.class
})
@EnableMongoRepositories
public class BatchMongoConfig {
    // 배치 + MongoDB 전용 설정
}

또는 application.properties에서 동일하게 제외할 수도 있습니다(일반적인 점검 기준):

1
2
3

spring.autoconfigure.exclude=\
  org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\
  org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration

이때 spring.data.mongodb.uri=mongodb://localhost/test 는 그대로 유지합니다.

4-2. RDBMS를 실제로 쓰는 경우 — datasource 속성 명시

MySQL을 실제로 쓴다면 application.properties에 정확한 키 이름으로 설정합니다. 스프링 부트 2.x부터는 하이픈 표기(driver-class-name) 를 사용합니다(카멜케이스 driverClassName과 대소문자/표기 불일치가 오류의 흔한 원인입니다).

1
2
3
4
5
6
7

spring.datasource.url=jdbc:mysql://localhost:3306/db
spring.datasource.username=root
spring.datasource.password=yourpassword
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.jpa.database-platform=org.hibernate.dialect.MySQL5Dialect
spring.jpa.generate-ddl=true
spring.jpa.hibernate.ddl-auto=update

몽고가 아니라 MySQL을 쓸 목적이라면 spring-boot-starter-data-mongodb와 spring-boot-starter-batch를 함께 두는 대신, RDBMS용 스타터(예: spring-boot-starter-data-jpa + MySQL 드라이버)로 구성을 단순화하는 것이 낫습니다.

4-3. 내장 DB로 임시 테스트하는 경우

배치 예제에서 관계형 DB가 필요하고 별도 서버가 없다면 H2를 추가해 내장 DB를 활성화할 수 있습니다(임시 해결책으로 적합).

1
2
3
4
5

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

5. 검증 명령

해결 뒤 성공 여부는 다음 명령으로 확인합니다.

1
2
3
4
5
6
7
8

# 클래스패스에 실제로 어떤 스타터가 들어있는지 확인
mvn -q dependency:tree

# (있으면) 프로파일 활성 여부 확인
mvn spring-boot:run -Dspring.profiles.active=dev

# 실제로 애플리케이션이 정상 기동하는지 확인
mvn spring-boot:run

기동 로그에서 APPLICATION FAILED TO START 가 사라지고, MongoDB 연동 프로젝트라면 Started ... in X seconds 와 Mongo 저장소 초기화 로그가 보이면 성공입니다. (환경과 빌드 도구에 따라 ./gradlew bootRun 으로 대체할 수 있습니다.)

6. 재발 방지 체크

• 의존성과 설정이 일치하는지: RDBMS 스타터를 넣었으면 spring.datasource.url + driver-class-name 을 함께 명시했는지 재확인
• MongoDB 전용 프로젝트: @EnableAutoConfiguration(exclude=...) 또는 spring.autoconfigure.exclude 로 DataSource 자동 설정을 끄고, Mongo 구성만 남겼는지 확인
• 명명 규칙: 스프링 부트 2.x 속성은 하이픈 표기(driver-class-name)가 맞는지 점검
• 프로파일 누락: DB 설정이 특정 profile에만 있는데 활성 profile이 없지 않은지 확인
• CI 설정 동기화: 로컬에서 돌던 설정이 CI에 반영돼 있는지, CI가 같은 properties를 읽는지 확인

DevTrace verdict

이 문제의 핵심은 MongoDB 서버가 실행 중인지가 아니라, 스프링 부트가 “관계형 DataSource"를 자동 구성하려는데 url과 드라이버를 결정하지 못하는 자동 설정의 문제라는 점이다. MongoDB만 쓰는 프로젝트라면 DataSource 자동 설정을 제외하고, 실제 RDBMS를 쓴다면 url과 driver-class-name(부트 2.x 하이픈 표기)을 명시해야 한다.

DevTrace 결론

이 오류의 핵심은 MongoDB 서버가 실행 중인지가 아니라, 스프링 부트가 DataSource를 자동 설정하려 하면서 ‘무엇에 연결할지’ 판단을 못 하는 데서 비롯된다는 점이다. MongoDB만 사용한다면 DataSource 자동 설정을 제외하고, RDBMS를 쓴다면 url과 driver-class-name을 명시해라.

원문 출처는 문제 발견의 단서이며, 위 판단과 점검 항목은 DevTrace의 독자 분석이다.

출처: StackOverflow 51221777 — Failed to configure a DataSource: ‘url’ attribute is not specified and no embedded datasource could be configured