Spring Boot 3.x 빌드 에러 해결 — "Dependency requires at least JVM runtime version 17" 원인과 해결법

한 줄 요약

build.gradle에 Java 버전을 설정해도 에러가 사라지지 않는 이유는, Gradle을 실행하는 JVM 자체가 여전히 구버전이기 때문이다.

A problem occurred configuring root project 'kuke-board'.
> Could not resolve all artifacts for configuration 'classpath'.
   > Could not resolve org.springframework.boot:spring-boot-gradle-plugin:3.2.2.
     Required by:
         root project : > org.springframework.boot:org.springframework.boot.gradle.plugin:3.2.2
      > Dependency requires at least JVM runtime version 17. This build uses a Java 11 JVM.
* Try:
> Run this build using a Java 17 or newer JVM.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.
You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.
For more on this, please refer to https://docs.gradle.org/8.14.4/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

---

핵심 개념 설명

Spring Boot 3.x의 Java 버전 요구사항

Spring Boot 공식 문서(Spring Boot 3.0 Release Notes)에 따르면,
Spring Boot 3.0부터는 Java 17 이상이 필수 요구사항이다.

Spring Boot 3.0 requires Java 17 as a minimum version.
— Spring Boot 3.0 Release Notes

 

즉, Spring Boot 3.3.2를 사용한다면 빌드 환경의 JVM도 반드시 Java 17 이상이어야 한다.

---

왜 build.gradle 설정만으로는 부족한가?

Gradle 공식 문서에 따르면, sourceCompatibility와 targetCompatibility는
생성할 바이트코드의 Java 버전 호환성을 지정하는 컴파일러 옵션이다.

sourceCompatibility = JavaVersion.VERSION_21

 

이 설정은 "Java 21 문법으로 소스코드를 컴파일하라" 는 지시일 뿐이다.
Gradle 자체를 실행하는 JVM 버전과는 완전히 별개다.

쉽게 말해, 두 가지 JVM이 존재한다.

구분	역할	설정 위치
Gradle JVM	Gradle 프로세스 자체를 실행	IDE Gradle 설정 or JAVA_HOME
컴파일 JVM	소스코드를 컴파일할 때 사용	build.gradle의 sourceCompatibility

에러는 Gradle JVM이 Java 11이었기 때문에 발생한 것이다.

---

쉽게 이해하는 설명

공장(Gradle)이 제품(코드)을 생산하는 상황으로 비유하면,

• sourceCompatibility 설정 = "제품 규격서에 적힌 사양"
• Gradle JVM = "실제로 공장을 돌리는 기계"

규격서에 아무리 최신 사양을 적어도,
공장 기계 자체가 구형이면 생산이 불가능하다.

---

해결 과정 (IntelliJ IDEA 기준)

1단계 — Java 21 설치

File → Project Structure → SDKs → + → Download JDK
→ Version: 21, Vendor: Microsoft OpenJDK (또는 Eclipse Temurin 등) 선택 후 다운로드

01

프로젝트 구조 > SDK 적용,확인

2단계 — Gradle JVM 변경 ← 핵심

File → Settings → Build, Execution, Deployment → Build Tools → Gradle
→ Gradle JVM 드롭다운을 기존 Java 11 → Java 21로 변경
→ Apply → OK

01

파일 > 설정 > 빌드 > Gradle > Gradle JVM 적용,확인

3단계 — 프로젝트 재빌드

Gradle 툴 창에서 Reload All Gradle Projects 실행 후 빌드 재시도

---

핵심 정리

• Spring Boot 3.x는 Java 17 이상을 공식적으로 요구한다
• build.gradle의 sourceCompatibility는 컴파일 대상 버전이며, Gradle 실행 JVM과 무관하다
• 에러의 실제 원인은 Gradle을 실행하는 JVM 버전이 낮은 것이다
• 해결은 IDE의 Gradle JVM 설정을 Java 17 이상으로 변경하는 것이다
• 프로젝트 SDK와 Gradle JVM 설정은 별도로 확인해야 한다

---

추가 정보

환경 변수 JAVA_HOME 확인

터미널에서 IDE 외부 환경도 확인하는 것이 좋다.

java -version
echo $JAVA_HOME   # macOS / Linux
echo %JAVA_HOME%  # Windows

 

시스템 JAVA_HOME이 Java 11로 설정된 경우, IDE 설정과 별도로 환경 변수도 갱신해야 한다.

Gradle Toolchains 활용 (권장)

Gradle 6.7부터는 Java Toolchains 기능을 공식 지원한다.
build.gradle에 아래와 같이 작성하면, Gradle이 명시된 버전의 JDK를 자동으로 탐지하거나 다운로드한다.

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

참고: Gradle Java Toolchains 공식 문서

 

이 방식은 팀원마다 JDK 버전이 다른 환경에서 일관성을 유지하는 데 효과적이다.