Spring Boot Failed to configure a DataSource 해결: JDBC URL·드라이버·프로필 점검 (2026년 9월)

Spring Boot 실행 직후 Failed to configure a DataSource와 'url' attribute is not specified가 표시되면, 현재 실행 환경에서 DB 연결 정보를 만들지 못했다는 뜻입니다. Spring Boot 3.5·4.1 공식 문서를 2026년 9월 3일에 확인해 점검 순서를 정리했습니다.

빠른 결론

외부 DB를 쓴다면 JDBC 드라이버 의존성과 spring.datasource.url을 함께 확인합니다.
H2 같은 내장 DB를 쓴다면 런타임 의존성이 실제 실행 classpath에 있는지 봅니다.
설정 파일이 따로 있다면 활성 프로필과 파일 이름이 일치하는지 확인합니다.

증상별 먼저 볼 곳

화면에 함께 보이는 내용	우선 점검
url attribute is not specified	현재 프로필의 JDBC URL
Failed to determine a suitable driver class	DB 드라이버 의존성과 URL 형식
로컬에서는 되고 서버에서만 실패	활성 프로필·환경 변수·외부 설정 파일
DB를 사용하지 않는 프로젝트	불필요한 JDBC/JPA starter 의존성

1. 오류 바로 위 로그부터 확인하기

APPLICATION FAILED TO START 위쪽을 봅니다. URL 누락과 드라이버 감지 실패가 함께 나오면 연결 문자열 또는 드라이버를 점검합니다. Access denied, Connection refused라면 DataSource는 만들어졌으므로 인증·주소·서버 상태를 따로 봐야 합니다.

2. 이 프로젝트가 DB를 쓰는지 먼저 결정하기

build.gradle 또는 pom.xml에서 JDBC·JPA starter가 필요한지 확인합니다. DB를 쓰지 않는데 복사 과정에서 들어왔다면 불필요한 starter를 제거합니다. 자동 설정 제외는 원인을 숨길 수 있어 첫 조치로 권하지 않습니다.

3. 외부 DB라면 JDBC URL을 현재 프로필에 넣기

MySQL을 예로 들면 src/main/resources/application.properties에 다음처럼 입력합니다. 실제 호스트·포트·DB 이름과 계정으로 바꾸되 운영 비밀번호를 Git에 커밋하면 안 됩니다.

spring.datasource.url=jdbc:mysql://localhost:3306/appdb
spring.datasource.username=appuser
spring.datasource.password=${DB_PASSWORD}

공식 문서에 따르면 JDBC URL로 드라이버를 자동 감지할 수 있습니다. driver-class-name을 먼저 강제하기보다 URL 형식과 드라이버 의존성을 맞추세요.

4. JDBC 드라이버가 실행 classpath에 있는지 확인하기

Gradle MySQL 프로젝트라면 의존성 예시는 다음과 같습니다. PostgreSQL을 사용한다면 해당 드라이버로 바꿉니다.

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    runtimeOnly("com.mysql:mysql-connector-j")
}

IntelliJ의 Gradle → Reload All Gradle Projects를 누릅니다. 터미널에서는 ./gradlew dependencies --configuration runtimeClasspath로 드라이버 포함 여부를 볼 수 있습니다. Windows에서는 ./gradlew.bat를 사용합니다.

5. 개발·테스트용 내장 DB라면 의존성만 확인하기

Spring Boot는 H2, HSQLDB, Derby 같은 내장 DB를 classpath에서 찾으면 연결 URL 없이 자동 구성할 수 있습니다. 테스트용 H2가 목적이라면 예를 들어 runtimeOnly("com.h2database:h2")가 실제 실행 구성에 포함됐는지 확인합니다. 내장 DB 데이터는 종료 후 사라질 수 있으므로 운영 데이터 저장용으로 착각하면 안 됩니다.

6. application-local 설정이 실제로 활성화됐는지 확인하기

URL을 application-local.properties에 넣었다면 실행 구성에서 프로필을 켜야 합니다. IntelliJ의 Run → Edit Configurations에서 Program arguments에 아래 옵션을 넣거나 환경에 맞는 방식으로 지정합니다.

--spring.profiles.active=local

공식 문서에 따르면 활성 프로필이 없을 때는 default 프로필이 사용됩니다. 또한 spring.profiles.active는 프로필 전용 파일 안이 아니라 기본 설정이나 명령줄처럼 비프로필 문서에서 지정해야 합니다. 시작 로그의 The following profiles are active 문구도 함께 확인하세요.

7. YAML 들여쓰기와 설정 위치 점검하기

application.yml의 datasource가 spring 아래에 있는지, 파일이 src/main/resources에 있는지 확인합니다. 배포 환경에서는 환경 변수가 로컬 값을 덮어쓸 수 있습니다.

주의사항

• DB 비밀번호·토큰을 글, 화면 캡처, Git 저장소에 남기지 않습니다.
• 운영 DB 주소를 로컬 테스트 값으로 바꾸기 전에 배포 환경과 백업 정책을 확인합니다.
• 오류를 숨기려고 DataSource 자동 설정을 제외하면 JPA·JDBC 기능도 동작하지 않을 수 있습니다.

그래도 해결되지 않을 때

1. ./gradlew clean bootRun으로 IDE 캐시와 별개로 재현되는지 봅니다.
2. 활성 프로필, JDBC URL의 접두사(jdbc:mysql: 등), 드라이버 의존성을 한 줄씩 대조합니다.
3. 그다음에야 DB 프로세스, 포트, 방화벽, 계정 권한을 확인합니다. 이 단계의 오류 문구는 URL 누락 오류와 다를 수 있습니다.

FAQ

Q1. driver-class-name을 꼭 적어야 하나요?

일반적인 자동 구성에서는 JDBC URL과 classpath의 드라이버로 감지할 수 있습니다. 커스텀 DataSource처럼 특별한 구성이 아니라면 URL·의존성부터 확인하세요.

Q2. application-dev.properties에 URL이 있는데 왜 실패하나요?

dev 프로필이 활성화되지 않았거나 더 높은 우선순위의 환경 변수가 값을 덮었을 수 있습니다. 실행 옵션과 시작 로그를 확인합니다.

Q3. H2를 추가하면 운영 DB 오류도 해결되나요?

아닙니다. H2는 개발·테스트용 내장 DB 선택지입니다. MySQL·PostgreSQL을 써야 한다면 해당 JDBC URL과 드라이버를 올바르게 구성해야 합니다.

관련 글

• Spring Boot Port 8080 was already in use 오류 해결
• IntelliJ Gradle JVM 버전 오류 해결
• IntelliJ Cannot resolve symbol 빨간 글씨 해결

공식 출처

• Spring Boot Reference: SQL Databases
• Spring Boot How-to: Data Access
• Spring Boot Reference: Profiles
• Spring Boot Reference: Externalized Configuration

확인 기준: 2026년 9월 3일, Spring Boot 공식 문서의 안정 버전 4.1.1 및 3.5.16 계열. 프로젝트 버전에 따라 메뉴와 의존성 표기가 다를 수 있습니다.