Android 프로젝트에서 Gradle 빌드 중 hiltJavaCompileDevDebug 단계에서 다음과 같은 오류가 발생할 수 있습니다:
Execution failed for task ':app:hiltJavaCompileDevDebug'.
> java.lang.IllegalStateException: Unable to read Kotlin metadata due to unsupported metadata version.
이 글에서는 위 오류의 원인과 해결 방법을 단계별로 설명합니다.
📌 오류 원인
이 오류는 Kotlin의 메타데이터 버전이 현재 컴파일러와 호환되지 않을 때 발생합니다. 보통 아래와 같은 경우에 발생합니다:
- Kotlin 버전 불일치 (모듈 또는 라이브러리 간)
- 빌드 캐시 문제
- Kotlin 컴파일러가 오래되었거나 너무 최신일 경우
- kapt 또는 Hilt annotation processor가 구버전을 참조하는 경우
✅ 해결 방법
1. Kotlin 버전 일관성 유지
모든 모듈에서 동일한 Kotlin 버전을 사용하고 있는지 확인하세요.
최신 Android 공식 권장 Kotlin 버전은 2.1.0입니다 (2025년 6월 기준).
// project-level build.gradle (또는 build.gradle.kts)
plugins {
id("org.jetbrains.kotlin.jvm") version "2.1.0" apply false
}
또는 Kotlin DSL 사용 시:
kotlin {
jvmToolchain(17)
}
2. Hilt 및 Kapt 관련 버전 확인
Hilt 또는 Kapt에서 Kotlin 메타데이터를 파싱할 수 없을 때도 발생할 수 있습니다.
최신 버전을 사용하는지 확인하세요:
// app/build.gradle
dependencies {
implementation("com.google.dagger:hilt-android:2.51")
kapt("com.google.dagger:hilt-android-compiler:2.51")
}
참고: Kotlin 2.1.0에서는 Hilt 2.51 이상을 사용하는 것이 안정적입니다.
3. 빌드 캐시 초기화
Gradle 캐시 문제일 가능성도 있습니다. 다음 명령어를 실행해 캐시를 제거하고 다시 빌드해보세요:
./gradlew clean build --no-build-cache
또는:
./gradlew clean --refresh-dependencies
4. Kotlin 메타데이터 오류를 발생시키는 라이브러리 제거
의심되는 외부 라이브러리가 구버전 Kotlin으로 컴파일되었을 수 있습니다. 예를 들어, 직접 작성한 Kotlin 코드가 아닌 Java-only 라이브러리에서 이 오류가 발생할 수 있습니다.
- 모든 라이브러리의 build.gradle 또는 build.gradle.kts에서 Kotlin 버전을 최신으로 맞춰야 합니다.
- buildSrc나 :core 등 별도 모듈이 있는 경우, Kotlin 버전이 project와 다르지 않도록 확인하세요.
🧪 디버깅 팁
- 아래 명령어로 어떤 파일이 문제인지 자세히 확인하세요:
./gradlew :app:hiltJavaCompileDevDebug --stacktrace --info
- 오류 로그 중 "unsupported metadata version" 뒤에 나오는 클래스를 유심히 살펴보세요. 해당 클래스가 구버전 Kotlin으로 작성되었을 수 있습니다.
📚 참고 자료
✅ 결론
Unsupported Kotlin metadata version 오류는 Kotlin과 관련된 버전 불일치가 주된 원인입니다. Kotlin, Hilt, kapt 버전을 최신으로 통일하고 캐시를 정리하면 대부분의 경우 해결됩니다. 문제가 지속된다면, 의심되는 라이브러리를 하나씩 제거하며 원인을 좁혀나가는 것이 좋습니다.
2025.06.16 일 기준
아래와 같은 버전 업데이트로 빌드 에러 해결 완료함.
Hilt 2.51 -> Hilt 2.56
