IntelliJ에서 Gradle 프로젝트 Sync 실패 해결하기: Java Toolchain, Project SDK, Gradle JVM 버전 불일치 트러블슈팅

최근 강사님이 제공한 Spring Boot 백엔드 프로젝트를 IntelliJ에서 열었는데, 프로젝트가 바로 실행되지 않고 Gradle Sync 단계에서 오류가 발생했다. 처음에는 IntelliJ 자체 문제이거나 Java가 제대로 설치되지 않은 줄 알았지만, 확인해보니 핵심 원인은 프로젝트가 요구하는 Java 버전과 내 로컬 환경 및 IntelliJ 설정이 서로 맞지 않았기 때문이었다.

이번 글에서는 어떤 오류가 발생했는지, 원인이 무엇이었는지, 그리고 어떻게 해결했는지 정리해보려고 한다.

---

문제 상황

IntelliJ에서 Gradle 프로젝트를 열었는데 Build/Sync 단계에서 여러 오류가 발생했다. 대표적으로 아래와 같은 메시지가 보였다.

• Project source sets cannot be resolved
• Could not resolve all dependencies for configuration ':compileClasspath'
• Undefined Toolchain Download Repositories

즉, IntelliJ가 Gradle 프로젝트를 읽어들이는 과정에서 필요한 source set과 의존성을 제대로 해석하지 못하고 있었다.

처음에는 Java 자체가 설치되지 않았다고 생각했지만, 터미널에서 확인해보니 Java는 이미 설치되어 있었다.

java -version

실행 결과는 다음과 같았다.

openjdk version "23.0.1" 2024-10-15
OpenJDK Runtime Environment (build 23.0.1+11-39)
OpenJDK 64-Bit Server VM (build 23.0.1+11-39, mixed mode, sharing)

즉, Java는 설치되어 있었지만 프로젝트는 여전히 Sync에 실패하고 있었다.

---

원인 분석

문제의 원인을 찾기 위해 build.gradle 파일을 확인했다. 그 결과 아래와 같은 설정이 들어 있었다.

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

이 설정은 이 프로젝트가 Java 17 기준으로 빌드되어야 한다는 의미다.

그런데 내 Mac에는 기본적으로 Java 23이 잡혀 있었고, IntelliJ에서도 Gradle JVM이 Java 23으로 설정되어 있었다. 즉, 최신 버전의 Java는 설치되어 있었지만 프로젝트는 그보다 낮은 버전인 Java 17을 정확히 요구하고 있었던 것이다.

정리하면 문제는 다음과 같았다.

• 프로젝트는 Java 17 toolchain을 요구함
• 내 로컬 기본 Java는 Java 23
• IntelliJ의 Project SDK와 Gradle JVM도 Java 17로 맞춰져 있지 않았음
• 그 결과 Gradle Sync 실패

즉, 자바가 없는 문제가 아니라 프로젝트 요구 버전과 로컬 설정 버전이 달라서 생긴 문제였다.

---

해결 과정

1. 설치된 Java 버전 확인

먼저 터미널에서 현재 설치된 JDK 목록을 확인했다.

/usr/libexec/java_home -V

처음에는 Java 23과 Java 21만 보였고, Java 17은 보이지 않았다.

그래서 Java 17이 설치되어 있는지 다시 확인했다.

brew install openjdk@17

결과는 이미 설치되어 있다는 메시지였다. 하지만 이상하게도 java_home -V에서는 Java 17이 목록에 뜨지 않았다.

즉, Homebrew로 설치는 되어 있었지만 macOS가 표준 JDK 위치에서 인식하지 못하고 있는 상태였다.

---

2. Java 17을 macOS가 인식하도록 연결

이 문제를 해결하기 위해 Homebrew의 Java 17을 macOS의 표준 Java 경로에 연결했다.

sudo ln -sfn "$(brew --prefix openjdk@17)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-17.jdk

이후 다시 설치된 JDK를 확인했다.

/usr/libexec/java_home -V

이번에는 다음과 같이 Java 17이 정상적으로 목록에 나타났다.

Matching Java Virtual Machines (3):
    23.0.1 ...
    21.0.7 ...
    17.0.18 ...

즉, 이제 macOS와 IntelliJ가 Java 17을 인식할 수 있는 상태가 되었다.

---

3. IntelliJ에서 Project SDK를 Java 17로 변경

그 다음 IntelliJ에서 프로젝트 SDK를 직접 변경했다.

경로는 다음과 같다.

• File
• Project Structure
• Project

여기서 SDK 항목이 처음에는 <No SDK> 또는 Java 23으로 잡혀 있었다. 드롭다운 목록에서 감지된 SDK 중 Homebrew OpenJDK 17.0.18을 선택했다.

즉, 프로젝트 자체가 참조하는 SDK를 Java 17로 맞춘 것이다.

---

4. IntelliJ에서 Gradle JVM도 Java 17로 변경

Project SDK만 바꾸는 것으로는 충분하지 않았다. Gradle이 실제로 빌드와 Sync를 수행할 때 사용하는 JVM도 Java 17로 맞춰야 했다.

경로는 다음과 같다.

• IntelliJ IDEA
• Settings
• Build, Execution, Deployment
• Build Tools
• Gradle

여기서 Gradle JVM이 기본적으로 openjdk-23으로 설정되어 있었는데, 이를 Homebrew OpenJDK 17.0.18로 변경했다.

즉, 최종적으로 아래 두 가지를 모두 Java 17로 맞췄다.

• Project SDK = Java 17
• Gradle JVM = Java 17

---

결과

설정을 변경한 후 다시 Gradle Sync를 진행했더니, 처음에 보이던 빨간 에러들이 사라졌다.

이전에는

• source set 관련 오류
• compileClasspath 의존성 해석 오류
• toolchain 관련 오류

등이 함께 발생했지만, Java 17로 버전을 맞춘 뒤에는 치명적인 오류가 해결되었다.

남아 있는 것은 일부 주황색 경고와 취약점 경고였는데, 이는 프로젝트 실행 자체를 막는 치명적 오류는 아니었다.

즉, 이번 문제의 핵심은 Gradle 프로젝트가 요구하는 Java toolchain 버전과 IntelliJ 설정 버전이 다르다는 점이었다.

---

이번 트러블슈팅에서 알게 된 점

이번 경험을 통해 가장 크게 느낀 점은,
“자바가 설치되어 있다”는 것과 “프로젝트가 요구하는 자바 버전에 맞게 설정되어 있다”는 것은 전혀 다른 문제라는 점이다.

처음에는 Java 23이 설치되어 있으니 당연히 괜찮을 거라고 생각했지만, 실제로는 프로젝트가 Java 17을 명시적으로 요구하고 있었기 때문에 IntelliJ와 Gradle도 그에 맞게 맞춰줘야 했다.

즉, Gradle/Spring Boot 프로젝트에서 문제가 생기면 단순히 최신 Java가 설치되어 있는지만 볼 것이 아니라 아래를 함께 확인해야 한다.

• build.gradle의 toolchain 설정
• IntelliJ의 Project SDK
• IntelliJ의 Gradle JVM

이 세 가지가 서로 다르면 Sync 실패나 빌드 오류가 발생할 수 있다.

---

재발 방지 방법

앞으로 비슷한 문제를 줄이기 위해서는 다음을 먼저 확인하면 좋다.

1. build.gradle에서 요구하는 Java 버전 먼저 보기

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

이 숫자가 곧 프로젝트가 요구하는 Java 버전이다. 프로젝트를 열자마자 이 값을 먼저 보는 습관이 중요하다.

2. IntelliJ의 Project SDK와 Gradle JVM을 같은 버전으로 맞추기

• Project SDK
• Gradle JVM

이 둘은 반드시 프로젝트 요구 버전과 같아야 한다.

3. Homebrew로 설치한 JDK가 macOS에서 안 보이면 링크 상태 확인하기

설치는 되어 있는데 IntelliJ나 java_home -V에 안 뜨는 경우가 있다. 이때는 표준 Java 경로에 연결이 되어 있는지 확인해야 한다.

---

마무리

이번 문제는 처음엔 IntelliJ 자체 오류처럼 보였지만, 실제 원인은 단순했다.

프로젝트는 Java 17로 빌드되도록 설정되어 있었는데, 내 로컬 환경과 IntelliJ는 Java 23 기준으로 동작하고 있었기 때문에 Gradle Sync가 실패한 것이었다.

Java 17을 제대로 인식시키고, IntelliJ의 Project SDK와 Gradle JVM을 모두 17로 맞춘 뒤에는 핵심 오류가 해결되었다.

이번 일을 통해, 앞으로 Gradle 프로젝트를 열 때는 무조건 먼저 코드부터 보기보다 프로젝트가 요구하는 Java 버전과 IDE 설정이 일치하는지부터 확인해야겠다는 걸 배웠다.

---

한 줄 요약

Gradle Sync 오류가 날 때는 자바 설치 여부만 보지 말고, 프로젝트의 toolchain 버전과 IntelliJ의 Project SDK / Gradle JVM이 일치하는지 먼저 확인하자.

---