라떼군 이야기

안드로이드 스튜디오 Ladybug: Java 21과 Gradle 버전 호환성 에러 해결 방법

Problem

안드로이드 스튜디오를 최신 버전인 Ladybug로 업데이트한 후, 프로젝트를 동기화(Sync)할 때 다음과 같은 에러 메시지가 발생하며 빌드에 실패하는 상황입니다.

Your build is currently configured to use incompatible Java 21.0.3 and Gradle 8.0.
Cannot sync the project.
...
The maximum compatible Gradle JVM version is 19.

이 문제는 기존 프로젝트가 Gradle 8.0과 같은 이전 버전을 사용하고 있는데, 안드로이드 스튜디오 Ladybug가 기본적으로 Java 21을 사용하도록 설정되어 있어 발생하는 호환성 충돌입니다. 당장 Gradle 버전을 올리기 어려운 상황에서 프로젝트를 정상적으로 빌드해야 합니다.

Background

Gradle은 빌드 도구로서 실행되기 위해 JVM(Java Virtual Machine) 환경이 필요합니다. 이를 ‘Gradle Daemon JVM’이라고 부르는데, 각 Gradle 버전마다 지원하는 Java 버전의 범위가 정해져 있습니다.

예를 들어, Gradle 8.0은 최대 Java 19까지만 지원합니다. 하지만 안드로이드 스튜디오 Ladybug는 기본 JDK로 Java 21을 포함하고 있습니다. 따라서 Gradle 8.0을 사용하는 프로젝트를 Java 21 환경에서 실행하려고 시도하면, Gradle이 해당 Java 버전을 인식하지 못해 호환성 에러가 발생하게 됩니다.

Solution

Gradle 버전을 업그레이드하지 않고 문제를 해결하는 가장 간단한 방법은 Gradle이 사용하는 JDK 버전을 호환 가능한 버전(Java 17)으로 낮추는 것입니다.

방법 1: 안드로이드 스튜디오 설정 변경 (Native Android)

안드로이드 스튜디오 내부 설정을 통해 Gradle이 사용할 JDK를 변경합니다.

  1. Settings (Mac: Android Studio > Settings, Win: File > Settings)를 엽니다.
  2. Build, Execution, Deployment > Build Tools > Gradle로 이동합니다.
  3. Gradle JDK 드롭다운 메뉴를 클릭합니다.
  4. Download JDK를 선택하고 다음 옵션으로 다운로드합니다.
    • Version: 17
    • Vendor: JetBrains Runtime (권장)
  5. 다운로드가 완료되면 해당 JDK(Java 17)를 선택하고 Apply를 누른 뒤 프로젝트를 다시 Sync 합니다.

방법 2: Flutter 프로젝트의 경우

Flutter를 사용 중이라면 CLI를 통해 JDK 경로를 명시적으로 지정해주어야 할 수 있습니다.

  1. 위 ‘방법 1’과 동일하게 안드로이드 스튜디오에서 JetBrains Runtime 17을 다운로드합니다.
  2. 다운로드된 경로를 확인합니다. (예: ~/Library/Java/JavaVirtualMachines/jbr-17.0.12/Contents/Home)
  3. 터미널에서 다음 명령어를 실행하여 Flutter가 해당 JDK를 사용하도록 설정합니다.
# Flutter 설정에 JDK 경로 지정 (경로는 본인의 환경에 맞게 수정)
flutter config --jdk-dir ~/Library/Java/JavaVirtualMachines/jbr-17.0.12/Contents/Home

# 설정 확인 및 상태 점검
flutter doctor -v

출력 결과 예시:

[✓] Android toolchain - develop for Android devices
    • Java binary at: .../jbr-17.0.12/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment JBR-17.0.12...

주의 사항: 모듈 관련 에러 발생 시

JDK를 17로 변경한 후에도 빌드 시 다음과 같은 에러가 발생할 수 있습니다.

module jdk.compiler does not export com.sun.tools.javac.main to unnamed module

이 경우 설정 변경이 캐시나 데몬에 제대로 반영되지 않은 것이므로, 컴퓨터를 재부팅하거나 안드로이드 스튜디오를 완전히 종료 후 다시 시작하면 해결됩니다.

Deep Dive

Gradle과 Java 버전 호환성 매트릭스

Gradle 버전에 따라 지원하는 Java 버전은 엄격하게 관리됩니다. 프로덕션 환경에서는 항상 이 호환성을 확인해야 합니다.

  • Gradle 8.5 이상: Java 21 지원
  • Gradle 8.3 이상: Java 20 지원
  • Gradle 7.6 이상: Java 19 지원
  • Gradle 7.3 이상: Java 17 지원

장기적인 해결책

JDK 버전을 낮추는 것은 임시방편일 수 있습니다. 장기적으로는 보안 패치와 빌드 속도 향상을 위해 Gradle 버전을 8.5 이상으로 업그레이드하고, 이에 맞춰 AGP(Android Gradle Plugin) 버전도 함께 올리는 것이 권장됩니다. 최신 AGP는 R8 컴파일러 최적화 및 빌드 캐싱 기능이 개선되어 빌드 시간을 단축시킬 수 있습니다.

Conclusion

안드로이드 스튜디오 Ladybug 업데이트 후 발생하는 빌드 에러는 IDE의 기본 Java 버전(21)과 프로젝트의 Gradle 버전(8.0 이하) 간의 불일치 때문입니다. 당장 Gradle을 업데이트할 수 없다면, IDE 설정에서 Gradle JDK를 Java 17로 변경하는 것이 가장 빠르고 안전한 해결책입니다. Flutter 개발자의 경우 flutter config 명령어를 통해 명시적으로 경로를 지정해 주어야 합니다.

References

February 6, 2026 ∙ android-studio gradle java flutter build-error
협업 및 후원 연락하기 →