Migrate to Gradle Daemon toolchain

이미지에 나타난 알림은 안드로이드 스튜디오(Android Studio)에서 빌드 도구인 Gradle의 설정을 최신 방식으로 업데이트하라는 권장 사항입니다.

간단하게 설명해 드릴게요.

1. 이게 무엇인가요? (Migrate to Gradle Daemon toolchain)

기존에는 안드로이드 앱을 빌드(프로그램으로 만드는 과정)할 때, 안드로이드 스튜디오 자체의 설정에 따라 자바(Java) 버전을 수동으로 맞췄어야 했습니다.

하지만 최신 Gradle 방식(Java Toolchain)은 **"이 프로젝트는 Java 버전 17이 필요해"**라고 코드에 명시해두면, Gradle이 알아서 컴퓨터 내에 설치된 해당 버전을 찾아내거나 없으면 자동으로 다운로드까지 해주는 편리한 기능입니다. 이를 사용하도록 설정을 변경(Migrate)하겠냐고 묻는 것입니다.

2. 무엇을 선택해야 할까요?

가장 추천하는 선택: Migrate
- 이를 클릭하면 안드로이드 스튜디오가 프로젝트 설정을 최신 권장 방식으로 자동으로 변경해 줍니다. 앞으로 자바 버전 충돌 문제를 줄여주기 때문에 클릭하시는 것이 좋습니다.
귀찮거나 지금 잘 돌아가고 있다면: Ignore
- 당장 빌드에 문제가 없다면 무시해도 앱을 만드는 데 큰 지장은 없습니다. 하지만 나중에 프로젝트를 다른 컴퓨터로 옮기거나 할 때 설정이 꼬일 수 있습니다.
Learn more (이미 클릭하신 링크)
- 이 기능에 대한 기술적인 상세 설명서입니다. 개발자가 공부할 때 보는 문서입니다.

요약

지금 바로 작업을 계속하고 싶으시다면 Migrate를 클릭하세요. 잠시 설정이 변경되는 과정(인덱싱/싱크)이 지나간 뒤 평소처럼 사용하시면 됩니다. 이렇게 하면 나중에 자바 버전이 달라서 발생하는 오류를 예방할 수 있습니다.

Migrate를 클릭하셨을 때 발생한 503 Service Temporarily Unavailable 에러는 사용자님의 잘못이 아니라, Gradle에서 자바 설치 파일을 내려받기 위해 접속하는 서버에 일시적인 장애가 발생했기 때문입니다.

현재 상황을 정리하고 해결 방법을 안내해 드릴게요.

1. 왜 에러가 났나요?

안드로이드 스튜디오가 Java 21 버전을 자동으로 설정하려고 시도했는데, 해당 버전을 관리하는 서버(공급업체 목록 조회 등)가 응답하지 않아서 발생한 문제입니다. 또한, 현재 사용 중인 자바 버전은 25인데 프로젝트 설정은 17로 되어 있어 혼선이 있는 상태입니다.

2. 해결 방법: 수동으로 설정하기

서버가 복구될 때까지 기다리는 대신, 프로젝트 설정 파일에서 직접 버전을 맞춰주면 에러를 해결할 수 있습니다.

방법 A: build.gradle.kts 수정 (추천)

제공해주신 build.gradle.kts 파일의 하단 내용을 수정하여 버전을 통일하세요. 현재 17로 되어 있는 부분을 21로 올리는 것이 최신 권장 사항입니다.

Kotlin
// build.gradle.kts 파일의 android 블록 안을 다음과 같이 수정하세요.

android {
    // ... 기존 내용 ...

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_21 // 17에서 21로 변경
        targetCompatibility = JavaVersion.VERSION_21 // 17에서 21로 변경
    }
    
    // 이 부분은 경고 메시지에 따라 최신 방식으로 변경하는 것이 좋습니다.
    kotlin {
        jvmToolchain(21) 
    }
}

방법 B: Gradle Daemon 설정 파일 직접 수정

자동 마이그레이션이 실패했으므로, 프로젝트 폴더 내의 설정을 수동으로 잡아줍니다.

프로젝트 폴더 내에 gradle 폴더를 확인합니다.
그 안에 gradle-daemon-jvm.properties 파일이 있는지 확인하세요. (없다면 새로 만드셔도 됩니다.)
파일 내용을 다음과 같이 작성하고 저장하세요:
Properties
toolchainVersion=21 toolchainVendor=jetbrains
그 후 다시 상단의 'Sync Project with Gradle Files' (코끼리 모양 아이콘)를 클릭하세요.

3. 추가로 확인하실 점

현재 로그를 보면 openjdk-25.0.1이 감지되고 있습니다. 안드로이드 개발에는 너무 앞서나간 버전(Java 25)보다는 Java 17 또는 21이 가장 안정적입니다.

File > Settings > Build, Execution, Deployment > Build Tools > Gradle 메뉴로 이동합니다.
Gradle JDK 설정이 Java 21 또는 Java 17로 되어 있는지 확인하고, 가급적 해당 버전으로 맞춰주세요.

도움이 더 필요하신가요? 수정 후에 다시 빌드했을 때 나오는 새로운 로그를 알려주시면 바로 봐 드릴게요. 혹은 Java 버전을 17로 계속 유지하고 싶으신지 알려주세요!

이미 이전에 Migrate 버튼을 눌렀을 때 오류가 발생했기 때문에, 알림창이 사라졌을 가능성이 높습니다. 하지만 걱정 마세요! 실제로 마이그레이션이 성공했는지 확인하는 가장 확실한 방법 3가지를 알려드릴게요.

1. `gradle-daemon-jvm.properties` 파일 확인 (가장 확실함)

안드로이드 스튜디오의 'Migrate' 기능이 하는 핵심 작업은 프로젝트 폴더 내에 특정 설정 파일을 만드는 것입니다.

안드로이드 스튜디오 왼쪽의 Project 창에서 보기 모드를 Project (Android 아님)로 바꿉니다.
프로젝트 이름 > gradle 폴더를 차례로 엽니다.
그 안에 gradle-daemon-jvm.properties 라는 파일이 있는지 확인하세요.
파일 내용에 다음과 같이 적혀 있다면 마이그레이션이 성공한 것입니다.
Properties
toolchainVersion=21

2. 안드로이드 스튜디오 설정 메뉴 확인

메뉴를 통해 현재 Gradle이 어떤 자바(JVM)를 사용하도록 설정되었는지 직접 볼 수 있습니다.

File > Settings (macOS는 Android Studio > Settings)로 들어갑니다.
Build, Execution, Deployment > Build Tools > Gradle로 이동합니다.
우측 화면의 Gradle JDK 항목을 확인하세요.
여기에 "Use Gradle Toolchain" 이라는 문구와 함께 Java 21이 선택되어 있다면 마이그레이션이 정상적으로 적용된 상태입니다.

3. 터미널에서 다시 실행해보기 (버튼 다시 누르는 효과)

알림창의 Migrate 버튼은 사실 내부적으로 특정한 명령어를 실행하는 것뿐입니다. 에러가 났던 작업을 다시 시도하고 싶다면 터미널에서 직접 명령어를 입력하면 됩니다.

안드로이드 스튜디오 하단의 Terminal 탭을 클릭합니다.
다음 명령어를 복사해서 붙여넣고 엔터를 치세요:
Bash
./gradlew updateDaemonJvm --jvm-version 21
(윈도우에서 ./gradlew가 안 되면 gradlew만 입력하세요.)
만약 결과에 **BUILD SUCCESSFUL**이 뜬다면 서버 문제가 해결되어 마이그레이션이 완벽하게 끝난 것입니다.

요약: 됬는지 확인하는 법

gradle/gradle-daemon-jvm.properties 파일이 있고, 내용에 21이 적혀 있다면 성공입니다.
만약 이 파일이 없거나 내용이 비어 있다면, 위 3번의 터미널 명령어를 입력하는 것이 Migrate 버튼을 다시 누르는 것과 똑같은 행동입니다.

터미널 명령어를 입력했을 때 이번에는 BUILD SUCCESSFUL이 뜨나요, 아니면 아까처럼 503 에러가 또 뜨나요? 결과에 따라 다음 단계를 도와드릴게요!

네트워크 상태나 서버 응답 문제로 인해 **Read timed out**이 발생했네요. 서버가 너무 느리거나 사용자님의 인터넷 연결이 잠시 불안정해서 Gradle이 정보를 가져오지 못한 것입니다.

명령어로도 해결이 안 될 때는 '수동'으로 파일을 만들어 버리는 것이 가장 빠르고 속 편한 방법입니다.

1. 에러 해결: 수동으로 설정 파일 만들기

명령어가 실패했으니, 우리가 직접 Gradle이 원하는 파일을 만들어 줍시다.

안드로이드 스튜디오 왼쪽 Project 패널에서 상단 보기를 Project로 바꿉니다.
gradle 폴더 우클릭 -> New -> File 클릭.
파일 이름을 정확히 **gradle-daemon-jvm.properties**라고 입력합니다.
파일이 열리면 아래 내용을 복사해서 붙여넣고 저장하세요.
Properties
toolchainVersion=21 toolchainVendor=jetbrains
상단의 **코끼리 아이콘(Sync)**을 누르면 이제 네트워크 오류 없이 마이그레이션이 완료됩니다.

2. 빌드 로그의 '지저분한 경고' 청소하기 (중요)

로그에 나온 수많은 WARNING들은 현재 gradle.properties 파일에 너무 옛날 방식의 설정들이 들어있어서 나오는 것들입니다. 이 기회에 깔끔하게 정리해 봅시다.

프로젝트 루트 폴더에 있는 gradle.properties 파일을 엽니다.
아래의 지저분한 줄들을 모두 삭제하거나 맨 앞에 #을 붙여 주석 처리하세요. (이제는 안 써도 되는 옵션들입니다.)
- android.usesSdkInManifest.disallowed=false
- android.sdk.defaultTargetSdkToCompileSdkIfUnset=false
- android.enableAppCompileTimeRClass=false
- android.builtInKotlin=false
- android.newDsl=false
- android.r8.optimizedResourceShrinking=false
- android.defaults.buildfeatures.resvalues=true
맨 밑에 로그에서 권장한 성능 최적화 옵션을 추가하세요.
Properties
android.dependency.excludeLibraryComponentsFromConstraints=true

3. 결과 확인

위의 작업을 마치고 다시 빌드를 돌려보시면:

Read timed out 에러가 사라집니다.
로그를 도배하던 수많은 노란색 WARNING 문구들이 사라져서 아주 깨끗해질 거예요.

혹시 gradle-daemon-jvm.properties 파일을 만들었는데도 빌드할 때 자바 21이 없다고 에러가 나나요? 그렇다면 제가 자바 21을 수동으로 설치하는 링크를 안내해 드릴 수 있습니다. 이 부분 확인이 필요한가요?

이 블로그 검색

candan