Android Gradle 빌드 오류 해결: Cached Files 문제 해결 방법개요

 

Android 프로젝트를 Gradle로 빌드하는 과정에서 metadata.bin (No such file or directory) 오류가 발생할 수 있습니다. 이 오류는 손상된 Gradle 캐시 파일로 인해 발생하는 경우가 많으며, 간단한 조치로 해결할 수 있습니다.

본 글에서는 이 오류의 원인과 해결 방법을 정리하여 안내합니다.

 

---

오류 원인

Gradle은 프로젝트의 빌드를 최적화하기 위해 캐시를 활용합니다. 하지만 특정 버전의 Gradle을 사용하거나 Gradle 캐시 파일이 손상되었을 경우, 빌드 과정에서 다음과 같은 오류가 발생할 수 있습니다.

> Could not load compiled classes for build file
  /Users/******/.gradle/caches/8.9/groovy-dsl/.../metadata.bin (No such file or directory)

이 오류는 Gradle이 필요한 캐시 파일을 찾지 못할 때 발생합니다.

---

해결 방법

1. Gradle 캐시 폴더 삭제 후 재시작

가장 확실한 해결 방법은 손상된 Gradle 캐시를 삭제하는 것입니다.

아래 명령어를 실행하면 기존 Gradle 캐시가 삭제되고, 빌드 시 자동으로 다시 다운로드됩니다.

rm -rf ~/.gradle

이후 프로젝트를 다시 빌드합니다.

./gradlew clean build

Android Studio 사용 시:

1. Android Studio를 종료합니다.
2. 위 명령어를 실행하여 캐시를 삭제합니다.
3. Android Studio를 다시 실행한 후, 프로젝트를 동기화(Sync)합니다.

2. 특정 Gradle 버전의 캐시만 삭제 (선택 사항)

만약 Gradle 전체를 삭제하는 것이 부담된다면, 문제가 발생한 특정 버전의 캐시만 삭제할 수도 있습니다.

예를 들어, Gradle 8.9 버전에서 오류가 발생했다면 다음 명령어를 실행합니다.

rm -rf ~/.gradle/caches/8.9/

그 후 다시 빌드합니다.

./gradlew clean build

3. Gradle 최신 버전으로 업데이트

Gradle 버전이 오래되었거나 특정 버전에서 버그가 존재할 경우, 최신 버전으로 업데이트하면 해결될 수 있습니다.

gradle wrapper --gradle-version latest

또는 gradle-wrapper.properties 파일을 열어 최신 버전으로 변경합니다.

distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip

이후 다시 빌드합니다.

./gradlew clean build

4. Android Studio에서 Gradle 설정 초기화

Gradle 설정이 꼬였을 가능성이 있으므로 다음을 확인합니다.

1. Android Studio → Preferences → Build, Execution, Deployment → Gradle
2. Gradle JDK가 올바른지 확인 (JDK 17 또는 21 권장)
3. "Use Gradle from: 'gradle-wrapper.properties'" 설정이 되어 있는지 확인
4. 변경 후 Invalidate Caches & Restart 실행

5. Gradle 실행 로그 확인

만약 위 방법으로 해결되지 않는다면, Gradle 실행 로그를 확인하여 원인을 파악할 수 있습니다.

./gradlew build --info
./gradlew build --debug

출력된 로그에서 추가적인 문제를 확인할 수 있습니다.

---

결론

Gradle 빌드 오류가 발생하는 원인은 다양한데, 가장 흔한 원인은 손상된 캐시 파일입니다.

이 문제를 해결하는 가장 쉬운 방법은 Gradle 캐시를 삭제하는 것입니다.

✅ 해결 방법 요약

1. Gradle 캐시 삭제 (rm -rf ~/.gradle)
2. Gradle 특정 버전 캐시만 삭제 (rm -rf ~/.gradle/caches/8.9/)
3. Gradle 최신 버전으로 업데이트 (gradle wrapper --gradle-version latest)
4. Android Studio에서 Gradle 설정 점검 및 초기화
5. Gradle 실행 로그 확인 (./gradlew build --info)

이 방법들을 차례로 시도하면 대부분의 Gradle 빌드 오류를 해결할 수 있습니다.

문제가 해결되었길 바랍니다! 🚀