[Android] Android aapt2 process unexpectedly exit 오류 해결 방법

Android aapt2 process unexpectedly exit 오류 해결 방법

개요

Android Studio에서 앱을 빌드하다가 'aapt2 process unexpectedly exit' 오류를 만나면 당황스럽습니다. 이 오류는 Android Gradle 플러그인과 Gradle 버전의 불일치로 인해 발생하며, 많은 개발자들이 겪는 흔한 빌드 오류 중 하나입니다.

이 글에서는 AAPT2가 무엇인지부터 오류의 정확한 원인, 그리고 단계별 해결 방법까지 상세히 설명합니다. 빌드 오류로 시간을 낭비하지 마시고, 이 가이드를 통해 빠르게 문제를 해결하세요.

목차

1. AAPT2 정의와 빌드 프로세스

2. 오류 발생 원인 분석

3. 단계별 해결 방법

4. 자주 묻는 질문(FAQ)

---

#1. AAPT2 정의와 빌드 프로세스

AAPT2는 Android Asset Packaging Tool 2의 약자로, Android 앱 빌드 시 필수적인 도구입니다. Android Studio와 Android Gradle 플러그인이 앱의 리소스를 컴파일하고 패키징하는 데 사용됩니다.

1) AAPT2란 무엇인가?

AAPT2는 Android 앱을 만들 때 흩어져 있는 리소스(이미지, 레이아웃, 문자열 등)를 모으고 압축하여 APK나 AAB 파일로 패키징하는 빌드 도구입니다. 리소스를 Android 플랫폼에 최적화된 바이너리 형식으로 파싱하고, 색인을 생성하며, 컴파일을 진행합니다.

(1) AAPT2의 주요 특징

① Android Gradle 플러그인 3.0.0 이상에서 기본적으로 활성화됩니다.

② 증분 컴파일을 지원하여 빌드 속도가 크게 향상되었습니다.

③ 리소스를 바이너리 형식으로 변환하여 APK 크기를 최적화합니다.

④ AAPT(버전 1)보다 더 정확한 오류 메시지를 제공합니다.

. . . . .

2) AAPT2 빌드 프로세스

AAPT2는 2단계 프로세스를 통해 리소스를 처리합니다. 각 단계를 이해하면 오류 발생 시 문제를 더 쉽게 파악할 수 있습니다.

(1) Compile 단계

첫 번째 단계에서 AAPT2는 리소스 파일들을 .flat 확장자를 가진 중간 바이너리 파일로 변환합니다. 이 단계에서는 다음 작업이 수행됩니다.

① XML 리소스 파일 파싱 및 검증

② 리소스 ID 생성 및 할당

③ 각 리소스를 개별 .flat 파일로 컴파일

④ PNG 이미지 최적화 (크런칭)

// Compile 단계 예시 출력
Compiling layout/activity_main.xml
Compiling drawable/icon.png
Compiling values/strings.xml
→ Output: .flat binary files

(2) Link 단계

두 번째 단계에서는 컴파일된 모든 .flat 파일을 병합하여 단일 APK 패키지로 만듭니다. 이 단계의 주요 작업은 다음과 같습니다.

① 모든 .flat 파일을 하나의 패키지로 병합

② R.java 파일 생성 (리소스 ID 클래스)

③ resources.arsc 파일 생성 (리소스 테이블)

④ ProGuard 규칙 파일 생성

// Link 단계 과정
Linking resources...
Merging manifest files
Processing resources.arsc
Generating R.java
→ Output: APK (without DEX, unsigned)

주의사항: Link 단계에서 생성된 APK는 아직 DEX 바이트코드를 포함하지 않으며 서명되지 않아 기기에 바로 배포할 수 없는 상태입니다. 이후 d8 도구로 DEX 변환, apksigner로 서명 과정을 거쳐야 합니다.

. . . . .

3) AAPT2와 빌드 도구 체인

AAPT2는 Android 빌드 시스템의 일부로, 다른 도구들과 함께 작동합니다.

도구	역할	처리 대상
AAPT2	리소스 컴파일/패키징	XML, 이미지, 문자열 등
D8/R8	DEX 변환 및 최적화	Java/Kotlin 바이트코드
apksigner	APK 서명	최종 APK 파일
zipalign	APK 최적화	서명된 APK

---

#2. 오류 발생 원인 분석

'aapt2 process unexpectedly exit' 오류는 AAPT2 프로세스가 예기치 않게 종료되었다는 의미입니다. 이 오류의 주요 원인을 정확히 이해하면 해결이 훨씬 쉬워집니다.

1) 주요 원인: Gradle 버전 불일치

이 오류의 가장 흔한 원인은 Android Gradle 플러그인(AGP) 버전과 Gradle 버전의 불일치입니다. 각 AGP 버전은 특정 Gradle 버전을 요구하며, 이 조합이 맞지 않으면 AAPT2가 제대로 작동하지 않습니다.

(1) 버전 불일치가 발생하는 상황

① Android Studio 수동 업데이트: build.gradle 파일을 직접 수정하여 AGP를 업그레이드할 때 Gradle 버전을 함께 업데이트하지 않은 경우

② 프로젝트 이전: 다른 개발 환경에서 작성된 프로젝트를 가져올 때 버전 충돌이 발생

③ Gradle 자동 업데이트 실패: Android Studio가 Gradle을 자동으로 업데이트하려 했으나 네트워크 문제 등으로 실패

(2) 호환 버전 매트릭스

아래 표는 각 Android Gradle 플러그인 버전에 필요한 최소 Gradle 버전을 보여줍니다. 최상의 성능을 위해 항상 최신 버전을 사용하는 것이 권장됩니다.

Android Gralde Plug 버전과 Gradle 버전을 업데이트

AGP 버전	최소 Gradle 버전	권장 Gradle 버전
8.5	8.7	8.9
8.4	8.6	8.7
8.3	8.4	8.6
8.2	8.2	8.4
8.1	8.0	8.2
8.0	8.0	8.1
7.4	7.5	7.6

중요: 표의 "최소" 버전은 작동 가능한 최저 버전이고, "권장" 버전은 최적 성능과 안정성을 위한 버전입니다.

. . . . .

2) 기타 발생 원인

Gradle 버전 불일치 외에도 다음과 같은 원인으로 이 오류가 발생할 수 있습니다.

(1) 손상된 리소스 파일

① XML 리소스 파일의 문법 오류

② 잘못된 형식의 이미지 파일

③ 중복된 리소스 ID

(2) Gradle 캐시 손상

① 빌드 중 중단으로 인한 캐시 파일 손상

② 디스크 공간 부족으로 인한 불완전한 다운로드

(3) JDK 버전 문제

① AGP 8.0 이상은 JDK 17 이상 필요

② 잘못된 JDK 경로 설정

---

#3. 단계별 해결 방법

이제 'aapt2 process unexpectedly exit' 오류를 해결하는 구체적인 방법을 단계별로 알아보겠습니다.

1) 방법 1: Gradle 버전 업데이트 (권장)

가장 효과적이고 근본적인 해결 방법은 Android Gradle 플러그인과 Gradle 버전을 올바르게 맞추는 것입니다.

(1) Android Studio UI를 통한 업데이트

① File > Project Structure 메뉴 선택

Android Studio 상단 메뉴에서 File을 클릭한 후 Project Structure를 선택합니다.

② Project 탭에서 버전 확인

왼쪽 메뉴에서 "Project"를 선택하고 다음 항목을 확인합니다.

- Android Gradle Plugin Version

- Gradle Version

③ Gradle 버전 업데이트

Gradle Version 드롭다운에서 AGP와 호환되는 버전을 선택합니다. #2의 호환 버전 표를 참고하세요.

④ Apply 및 OK 클릭

변경사항을 적용하면 Android Studio가 자동으로 Gradle을 다운로드합니다.

(2) gradle-wrapper.properties 직접 수정

또는 프로젝트의 gradle-wrapper.properties 파일을 직접 수정할 수 있습니다.

# gradle/wrapper/gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
# 아래 줄을 원하는 Gradle 버전으로 변경
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

(3) Gradle Sync 실행

버전을 변경한 후 반드시 File > Sync Project with Gradle Files를 실행하여 변경사항을 적용합니다.

// Sync 과정
Downloading Gradle 8.7...
Resolving dependencies...
Build completed successfully

. . . . .

2) 방법 2: Gradle 캐시 정리

버전을 업데이트해도 문제가 계속되면 손상된 Gradle 캐시가 원인일 수 있습니다.

(1) Android Studio Clean 실행

// 메뉴: Build > Clean Project
Cleaning build directory...
Removing intermediate files...
Clean completed

(2) Gradle 캐시 수동 삭제

① 프로젝트의 .gradle 폴더 삭제

② 사용자 홈의 .gradle 캐시 삭제 (Windows: C:\Users\사용자명\.gradle)

③ Android Studio 재시작

④ Sync Project with Gradle Files 실행

(3) Invalidate Caches 실행

File > Invalidate Caches / Restart 메뉴를 선택하여 Android Studio의 모든 캐시를 초기화합니다.

. . . . .

3) 방법 3: build.gradle 직접 수정

UI가 아닌 직접 코드를 수정하여 해결할 수도 있습니다.

(1) 프로젝트 레벨 build.gradle

// build.gradle (Project level)

buildscript {
    dependencies {
        // AGP 버전을 최신 안정 버전으로 업데이트
        classpath 'com.android.tools.build:gradle:8.5.0'
    }
}

(2) settings.gradle 확인

// settings.gradle

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

. . . . .

4) 검증 및 확인

문제가 해결되었는지 다음 방법으로 확인합니다.

① Build > Rebuild Project 실행

② 빌드 로그에서 "BUILD SUCCESSFUL" 메시지 확인

③ 앱을 에뮬레이터나 실제 기기에서 실행

// 성공적인 빌드 출력
BUILD SUCCESSFUL in 1m 23s
156 actionable tasks: 156 executed

Build Analyzer results available

---

#4. 자주 묻는 질문(FAQ)

1) Q: Gradle 버전을 업데이트했는데도 오류가 계속 발생합니다.

A: 다음 순서로 문제를 해결해보세요.

① Gradle 캐시 삭제: .gradle 폴더를 완전히 삭제

② Invalidate Caches: Android Studio 캐시 초기화

③ JDK 버전 확인: AGP 8.0 이상은 JDK 17 필요

④ 리소스 파일 검증: XML 문법 오류나 손상된 이미지가 없는지 확인

위 방법을 모두 시도해도 해결되지 않으면, 새 프로젝트를 만들어 코드를 옮기는 것도 고려해보세요.

. . . . .

2) Q: AGP와 Gradle 버전을 어떻게 확인하나요?

A: 다음 두 파일에서 확인할 수 있습니다.

AGP 버전 확인

// build.gradle (Project level)
dependencies {
    classpath 'com.android.tools.build:gradle:8.5.0'
    // ↑ 이 숫자가 AGP 버전
}

Gradle 버전 확인

// gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
// ↑ gradle-8.7이 Gradle 버전

또는 File > Project Structure > Project 메뉴에서 GUI로 확인할 수 있습니다.

. . . . .

3) Q: 최신 버전으로 업데이트하면 기존 코드가 깨지나요?

A: 대부분의 경우 문제없지만, 메이저 버전 업그레이드 시 일부 변경이 필요할 수 있습니다.

주의사항

① AGP 7.x → 8.x: JDK 17 이상 필요, namespace 설정 필수

② Deprecated API 경고 확인 및 수정

③ 라이브러리 호환성 확인 (특히 서드파티 라이브러리)

권장 방법: 별도 브랜치에서 먼저 테스트한 후 메인 브랜치에 병합하세요.

. . . . .

4) Q: Gradle 다운로드가 너무 느리거나 실패합니다.

A: 네트워크 문제일 수 있습니다. 다음 방법을 시도해보세요.

① 미러 저장소 사용

// settings.gradle
pluginManagement {
    repositories {
        // 중국 사용자를 위한 알리바바 미러
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        gradlePluginPortal()
        google()
    }
}

② Gradle 수동 다운로드

- https://gradle.org/releases/ 에서 직접 다운로드

- ~/.gradle/wrapper/dists/ 폴더에 압축 해제

③ 프록시 설정

# gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

. . . . .

5) Q: 특정 리소스 파일 때문에 AAPT2 오류가 발생합니다.

A: AAPT2는 리소스 검증이 엄격합니다. 다음을 확인하세요.

XML 리소스 검증

① 닫히지 않은 태그가 있는지 확인

② 속성값에 특수문자가 올바르게 이스케이프되었는지 확인

③ 중복된 ID가 없는지 확인

이미지 파일 검증

① PNG 파일이 손상되지 않았는지 확인

② 파일명에 허용되지 않는 문자(대문자, 특수문자)가 없는지 확인

③ drawable 폴더에 파일이 올바르게 위치했는지 확인

오류 메시지에 표시된 파일을 찾아 직접 검증하거나, 해당 파일을 임시로 제거한 후 빌드가 성공하는지 확인해보세요.

. . . . .

6) Q: JDK 버전을 어떻게 변경하나요?

A: Android Studio에서 다음과 같이 변경합니다.

① File > Settings (Mac: Preferences)

② Build, Execution, Deployment > Build Tools > Gradle

③ Gradle JDK 드롭다운에서 JDK 선택

AGP 8.0 이상은 JDK 17 이상 필수입니다. Android Studio에 내장된 JDK를 사용하거나, 별도로 설치한 JDK를 지정할 수 있습니다.

// gradle.properties에서 JDK 지정
org.gradle.java.home=/path/to/jdk-17

. . . . .

7) Q: 멀티 모듈 프로젝트에서는 어떻게 해야 하나요?

A: 멀티 모듈 프로젝트는 루트 프로젝트의 설정이 모든 모듈에 적용됩니다.

확인할 위치

① 루트 build.gradle의 AGP 버전

② gradle-wrapper.properties의 Gradle 버전

③ 각 모듈의 build.gradle이 루트 설정을 따르는지 확인

모든 모듈에서 동일한 AGP 버전을 사용해야 하며, 일부 모듈만 다른 버전을 사용하면 빌드 오류가 발생할 수 있습니다.

. . . . .

8) Q: AAPT2를 비활성화할 수 있나요?

A: 권장되지 않지만 다음과 같이 비활성화할 수 있습니다.

// gradle.properties
android.enableAapt2=false

하지만 AAPT2는 AGP 3.0.0 이상에서 필수이며, 비활성화하면 다음 문제가 발생합니다.

① 빌드 속도 저하

② 증분 빌드 미지원

③ 최신 Android 기능 사용 불가

④ 향후 AGP 버전과 호환 불가

근본적인 해결책은 AAPT2 오류 원인을 찾아 수정하는 것입니다. 비활성화는 임시 방편일 뿐입니다.

---

마무리

'aapt2 process unexpectedly exit' 오류는 Android 개발자들이 자주 만나는 빌드 오류 중 하나입니다. 이 글에서 다룬 내용을 요약하면 다음과 같습니다.

핵심 원인

① Android Gradle 플러그인과 Gradle 버전 불일치

② 손상된 Gradle 캐시

③ JDK 버전 불일치

④ 손상된 리소스 파일

해결 방법

① File > Project Structure에서 Gradle 버전 업데이트

② gradle-wrapper.properties 직접 수정

③ Gradle 캐시 정리 (Clean Project, Invalidate Caches)

④ JDK 버전 확인 및 변경

대부분의 경우 Gradle 버전을 AGP와 호환되는 버전으로 업데이트하면 문제가 해결됩니다. 호환 버전 표를 참고하여 올바른 조합을 선택하고, Sync Project with Gradle Files를 실행하여 변경사항을 적용하세요.

이 오류로 더 이상 개발 시간을 낭비하지 마시고, 이 가이드를 통해 빠르게 해결하시기 바랍니다. AAPT2의 개념을 이해하고 나면 향후 비슷한 빌드 오류도 더 쉽게 대응할 수 있을 것입니다.

긴 글 읽어주셔서 감사합니다.

끝.