MultiDex keep file missing 오류 해결 방법 [안드로이드 스튜디오]

 

안녕하세요! 안드로이드 개발을 하다 보면 프로젝트의 규모가 커짐에 따라 다양한 빌드 오류를 마주하게 됩니다. 그중에서도 특히 개발자를 당황스럽게 만드는 오류 중 하나가 바로 "MultiDex keep file missing"입니다.

이 오류는 주로 앱의 메서드 수가 65,536개(64K)를 초과하여 멀티덱스(MultiDex)를 적용하는 과정에서, 특정 클래스를 메인 덱스 파일에 유지하기 위한 설정 파일(keep file)을 찾지 못할 때 발생합니다. 오늘은 이 문제의 원인을 심층 분석하고, 가장 확실하게 해결할 수 있는 3가지 방법을 단계별로 알아보겠습니다.

---

1. MultiDex Keep File 오류의 발생 원인 이해하기

먼저 왜 이런 오류가 발생하는지 근본적인 이유를 알아야 합니다. 안드로이드 앱의 실행 파일인 DEX(Dalvik Executable) 파일은 설계상 하나의 파일 안에 담을 수 있는 메서드 참조 수가 65,536개로 제한되어 있습니다. 이를 해결하기 위해 여러 개의 DEX 파일을 만드는 'MultiDex' 기법을 사용하게 되죠.

이때, 앱이 실행될 때 가장 먼저 로드되어야 하는 핵심 클래스들(Application, Activity 등)은 반드시 첫 번째 DEX 파일(classes.dex)에 포함되어야 합니다. 이를 지정해주는 것이 바로 'Keep File'인데, 다음과 같은 상황에서 오류가 발생합니다.

• 파일 경로 설정 오류: multiDexKeepFile 또는 multiDexKeepProguard 속성에 지정된 경로에 실제 파일이 없는 경우.
• Gradle 플러그인 버전 이슈: Android Gradle Plugin(AGP) 버전이 업데이트되면서 기존 설정 방식과 충돌이 발생하는 경우.
• 빌드 캐시 오염: 이전 빌드의 잔재가 남아있어 새롭게 생성된 설정 파일을 제대로 인식하지 못하는 경우.

---

2. 단계별 해결 방법: 기본 점검부터 설정 변경까지

오류를 해결하기 위해 아래 순서대로 진행해 보시기 바랍니다. 대부분 2단계 내에서 해결됩니다.

방법 1: 빌드 클린 및 캐시 초기화 (가장 먼저 시도)

의외로 많은 빌드 오류가 단순한 캐시 문제입니다. Android Studio 상단 메뉴에서 다음 과정을 수행하세요.

1. Build -> Clean Project 선택
2. File -> Invalidate Caches / Restart... 선택 후 재시작
3. 재시작 후 Build -> Rebuild Project 실행

방법 2: build.gradle 설정 확인 및 수정

앱 수준의 build.gradle 파일에서 멀티덱스 관련 설정이 올바른지 확인해야 합니다. 특히 multiDexKeepFile 경로 선언 부분을 유심히 살펴보세요.

android {
    defaultConfig {
        ...
        multiDexEnabled true
    }
    
    buildTypes {
        release {
            // 아래 줄이 문제일 확률이 높습니다. 파일이 실제 존재하는지 확인하세요.
            // multiDexKeepFile file('multidex-config.txt') 
            
            // 또는 Proguard 스타일을 사용한다면:
            // multiDexKeepProguard file('multidex-config.pro')
        }
    }
}

Tip: 만약 특정 클래스를 수동으로 유지할 필요가 없다면, 위 multiDexKeepFile 관련 라인을 주석 처리하거나 삭제한 뒤 빌드해 보세요. 최근의 R8 컴파일러는 자동으로 최적화를 잘 해주기 때문에 명시적인 선언 없이도 해결되는 경우가 많습니다.

방법 3: multidex-config.txt 파일 직접 생성

만약 반드시 특정 클래스를 메인 덱스에 포함해야 한다면, 누락된 파일을 직접 생성해 주어야 합니다. app 모듈 루트 디렉토리에 multidex-config.txt 파일을 만들고 내용을 작성하세요.

// 예시: 메인 덱스에 포함할 클래스 경로 기입
com/example/myapp/MyApplication.class
com/example/myapp/MainActivity.class

---

3. 최신 Android 환경에서의 권장 설정 (AGP 7.0 이상)

최신 안드로이드 스튜디오와 Gradle 버전을 사용하고 있다면, 더 이상 복잡한 multiDexKeepFile 설정에 매달릴 필요가 없습니다. 안드로이드 5.0(API 레벨 21) 이상을 최소 SDK 버전으로 사용하는 앱은 기본적으로 멀티덱스를 지원하기 때문입니다.

minSdkVersion이 21 이상인 경우:

• multiDexEnabled true 설정만으로 충분합니다.
• 별도의 keep 파일을 관리하지 않아도 시스템이 알아서 처리합니다.

R8 컴파일러 활용:
ProGuard의 후속인 R8은 멀티덱스 분석 능력이 훨씬 뛰어납니다. 만약 구버전 설정을 그대로 마이그레이션 했다면, multiDexKeepProguard 옵션을 사용하여 ProGuard 규칙 형식으로 관리하는 것이 가독성과 유지보수 면에서 더 유리합니다.

---

📌 핵심 요약 정리

• ✅ 원인: 멀티덱스 빌드 시 메인 덱스에 유지할 클래스 목록 파일(keep file)을 찾지 못함.
• ✅ 해결 1: Clean Project와 Invalidate Caches를 통해 빌드 환경 초기화.
• ✅ 해결 2: build.gradle에서 multiDexKeepFile 경로가 올바른지, 혹은 불필요하게 선언되지 않았는지 확인.
• ✅ 해결 3: 수동 관리가 필요하다면 app 폴더에 파일을 직접 생성하거나 R8/ProGuard 규칙으로 대체.
• ✅ 권장: minSdkVersion이 21 이상이라면 설정을 단순화하여 시스템 자동 관리에 맡길 것.