IntelliJ Gradle JVM 버전 오류 해결: Unsupported class file major version 점검법
확인 기준: 2026년 7월 31일, IntelliJ IDEA·Gradle 공식 문서
IntelliJ IDEA에서 Gradle 프로젝트를 열 때 Unsupported class file major version 또는 JDK 호환 오류가 나오면 한 가지 Java 설정만 바꾸기보다 ‘Gradle을 실행하는 JVM’과 ‘코드를 컴파일하는 JDK’를 나눠 봐야 합니다.
빠른 결론
먼저 프로젝트 루트에서 Gradle과 JVM의 실제 버전을 확인하고, IntelliJ의 Gradle JVM과 Wrapper 버전을 공식 호환표에 맞추세요. Project SDK·Gradle JVM·Toolchain은 역할이 다르므로 무조건 같은 값으로 바꾸면 안 됩니다.
세 가지 Java 설정부터 구분하기
| 설정 | 역할 | 확인 위치 |
|---|---|---|
| Project SDK | IDE의 프로젝트·모듈 SDK | Project Structure |
| Gradle JVM | Gradle 자체를 실행하는 JVM | Settings > Build Tools > Gradle |
| Java Toolchain | 컴파일·테스트에 사용할 Java | build.gradle(.kts) |
JetBrains 공식 문서에 따르면 기존 프로젝트의 Gradle JVM을 정할 때 IntelliJ는 먼저 gradle.properties의 org.gradle.java.home, 다음으로 JAVA_HOME, 그다음 현재 Gradle과 호환되는 JDK를 확인합니다.
Java·Gradle 런타임 호환표
아래는 Gradle 공식 호환성 문서에서 2026년 7월 31일에 다시 확인한 ‘Gradle을 실행할 수 있는 최소 버전’입니다. 컴파일용 Toolchain 지원 시작 버전과는 구분해야 합니다.
| Gradle 실행 JVM | 필요한 Gradle 버전 |
|---|---|
| Java 17 | 7.3 이상 |
| Java 21 | 8.5 이상 |
| Java 25 | 9.1.0 이상 |
| Java 26 | 9.4.0 이상 |
점검 체크리스트
- 명령줄과 IntelliJ가 같은 Gradle JVM을 사용하는가
- 프로젝트에
gradlew,gradlew.bat,gradle-wrapper.properties가 있는가 org.gradle.java.home,JAVA_HOME, Toolchain이 서로 다른 버전을 가리키는가
IntelliJ Gradle JVM 오류 해결 순서
- 실제 버전 확인: 프로젝트 루트에서 Windows는
gradlew.bat --version, macOS·Linux는./gradlew --version을 실행합니다. 출력의 Gradle과 JVM 항목을 기록합니다. - Wrapper 확인:
gradle/wrapper/gradle-wrapper.properties의distributionUrl에서 프로젝트가 요구하는 Gradle 버전을 확인합니다. - Gradle JVM 확인: IntelliJ에서
Ctrl+Alt+S를 누르고 Build, Execution, Deployment > Build Tools > Gradle로 이동합니다. - 호환표 대조: 선택된 Gradle JVM이 현재 Wrapper 버전에서 실행 가능한지 위 표와 공식 문서로 확인합니다.
- 우선 적용값 점검: 프로젝트와 사용자 홈의
gradle.properties에org.gradle.java.home이 있는지 보고, 터미널의JAVA_HOME도 확인합니다. - Project SDK 분리 확인: Project Structure의 SDK와 Gradle JVM이 다른 이유가 있는지 확인합니다.
- Toolchain 확인:
build.gradle또는build.gradle.kts의languageVersion이 프로젝트 의도와 맞는지 봅니다. - 한 가지씩 수정: 호환되는 JDK를 Gradle JVM으로 선택하거나 팀이 정한 버전으로 Wrapper를 올린 뒤 Gradle Reload를 실행하고 다시 빌드합니다.
주의사항과 추가 점검
- Wrapper 버전을 임의로 최신으로 올리기 전에 Spring Boot, Android Gradle Plugin, Kotlin 등 플러그인의 지원 범위를 먼저 확인하세요.
org.gradle.java.home에 개인 PC의 절대 경로를 넣으면 다른 팀원이나 CI에서 실패할 수 있습니다.- 캐시 삭제는 버전 호환을 고치는 방법이 아닙니다. 설정을 맞춘 뒤에도 오래된 인덱스나 Daemon이 남았을 때만 Gradle Daemon 재시작이나 IntelliJ 캐시 무효화를 검토하세요.
계속 실패하면 멀티 모듈별 Toolchain, 오류를 낸 플러그인과 의존성이 더 높은 Java로 빌드됐는지, IDE 터미널과 외부 터미널의 JAVA_HOME이 다른지를 확인합니다.
자주 묻는 질문
Q1. Gradle JVM과 Project SDK는 꼭 같아야 하나요?
아닙니다. Gradle JVM은 빌드 도구 실행용이고 Project SDK와 Toolchain은 프로젝트 코드에 관여합니다. 다르게 구성할 수 있지만 각 버전의 목적과 호환 범위가 분명해야 합니다.
Q2. gradlew와 gradlew.bat 중 무엇을 사용하나요?
Windows는 gradlew.bat, macOS·Linux는 ./gradlew를 사용합니다. 두 파일은 같은 Wrapper 설정을 읽어 프로젝트가 지정한 Gradle 버전을 실행합니다.
Q3. Unsupported class file major version 숫자를 외워야 하나요?
그럴 필요는 없습니다. 에러가 발생한 빌드의 Gradle·JVM·Toolchain 버전을 확인한 뒤 최신 Gradle 공식 호환표와 대조하는 편이 정확합니다.