TIL

오늘 배운 것

Gradle metadata.bin 오류 분석 및 Gradle Daemon을 통한 해결 사례

1. 문제 정의

Gradle 프로젝트 빌드 중 caches 디렉토리 내 metadata.bin 파일 관련 오류가 발생했다. 최초 오류 메시지는 다음과 같았다.

/home/gint/.gradle/caches/8.10.2/transforms/.../metadata.bin (No such file or directory)

해당 오류는 Gradle이 빌드 과정에서 사용하는 변환(transform) 캐시의 메타데이터 파일이 존재하지 않을 때 발생하는 문제다.

2. 초기 해결 시도 및 문제 재현

오류의 일반적인 원인으로 지목되는 캐시 손상을 해결하기 위해, 표준적인 해결 절차인 Gradle 캐시 디렉토리 삭제를 진행했다.

rm -rf ~/.gradle/caches

하지만 캐시 삭제 후 ./gradlew build 명령으로 빌드를 재시도했을 때, 문제는 해결되지 않고 동일한 유형의 오류가 다시 발생했다. 오류 메시지는 Could not read workspace metadata로 일부 변경되었으나, 근본적으로 캐시 파일에 접근하지 못하는 현상은 동일했다.

이러한 재현성을 통해, 문제는 정적인 캐시 파일의 손상이 아니라 빌드 시 캐시를 재생성하는 과정 자체에 결함이 있음을 추정할 수 있었다.

3. 근본 원인 분석

단순 캐시 삭제로 해결되지 않는 문제의 원인으로 백그라운드에서 실행되는 Gradle Daemon 프로세스를 지목했다.

Gradle Daemon은 빌드 성능 향상을 위해 JVM을 재사용하는 영속적인 프로세스다. 만약 이 데몬이 비정상적인 상태(예: 파일 핸들 누수, 내부 상태 오류)에 진입한 경우, 파일 시스템에 대한 정상적인 접근을 방해할 수 있다.

이에 따라, 비정상 상태의 Gradle Daemon이 캐시 디렉토리의 재생성 과정을 방해하여 불완전하거나 손상된 캐시 파일을 생성한다는 가설을 수립했다.

4. 해결 절차

상기 가설을 바탕으로, Gradle Daemon을 완전히 초기화하고 캐시를 재생성하는 체계적인 절차를 수립 및 실행했다.

1단계: 모든 Gradle Daemon 프로세스 중지

--stop 옵션을 사용하여 현재 실행 중인 모든 Gradle Daemon 인스턴스를 종료시켰다.

./gradlew --stop

2단계: 관련 캐시 디렉토리 완전 삭제

Daemon 종료 후, 잔여 상태 정보가 남지 않도록 사용자 홈 디렉토리의 캐시와 프로젝트 레벨의 캐시를 모두 삭제했다.

# 사용자 홈 디렉토리의 캐시 삭제
rm -rf ~/.gradle/caches/

# 프로젝트 루트 디렉토리의 캐시 삭제
rm -rf .gradle/

3단계: 빌드 재실행

모든 관련 프로세스 및 파일이 초기화된 상태에서 빌드를 다시 실행했다.

./gradlew build

빌드 재실행 결과, metadata.bin 관련 오류는 더 이상 발생하지 않았다. 빌드 프로세스는 정상적으로 다음 단계로 진행되었고, 이후 class file not found와 같은 일반적인 컴파일 종속성 오류가 출력되었다. 이는 최초의 원인 불명 캐시 오류가 완전히 해결되었음을 의미한다.

> Task :jetty9:compileJava FAILED
class file for com.github.benmanes.caffeine.cache.LoadingCache not found
...

BUILD FAILED

5. 결론

Gradle 빌드 중 metadata.bin 관련 캐시 오류가 반복적으로 발생하고 일반적인 캐시 삭제로 해결되지 않을 경우, 근본 원인은 Gradle Daemon의 비정상적인 상태일 가능성이 높다.

이러한 문제에 직면했을 때, 단순히 캐시 디렉토리만 삭제할 것이 아니라 Gradle Daemon을 먼저 중지시키고, 사용자 레벨과 프로젝트 레벨의 캐시를 모두 삭제하는 포괄적인 초기화 절차를 수행하는 것이 효과적인 해결책이다. 이 절차는 보이지 않는 프로세스 상태로 인해 발생하는 예측 불가능한 빌드 실패를 해결하는 데 유효한 방법론이다.

TIL

TIL