Program type already present 오류 해결 방법 (안드로이드 스튜디오)

 

안녕하세요! 안드로이드 앱 개발을 하다 보면 빌드 과정에서 우리를 가장 당혹스럽게 만드는 오류 중 하나가 바로 "Program type already present"입니다. 잘 작동하던 코드가 라이브러리 하나 추가했을 뿐인데 갑자기 빌드 실패로 이어지면 막막할 수밖에 없죠.

오늘은 이 오류가 왜 발생하는지, 그리고 초보자부터 숙련자까지 단계별로 적용할 수 있는 확실한 해결 방법들을 정리해 보았습니다. 이 글을 끝까지 읽으시면 더 이상 중복 클래스 문제로 시간을 허비하지 않게 되실 겁니다.

 

---

1. "Program type already present" 오류란 무엇인가?

이 에러의 핵심은 '중복'입니다. 안드로이드 빌드 시스템인 Gradle이 앱을 컴파일하고 DEX 파일(안드로이드 실행 파일)을 만드는 과정에서, 동일한 경로와 이름을 가진 클래스 파일이 두 개 이상 발견될 때 발생합니다.

예를 들어, com.example.Helper라는 클래스가 A라는 라이브러리에도 들어있고, B라는 라이브러리에도 들어있다면 시스템은 "어떤 클래스를 최종 앱에 포함해야 할지 모르겠다"며 빌드를 중단해 버리는 것이죠. 이는 주로 다음과 같은 상황에서 발생합니다.

• 동일한 라이브러리의 서로 다른 버전이 중복으로 포함될 때
• 서로 다른 라이브러리가 내부적으로 같은 오픈소스 라이브러리를 포함(Internal Dependency)하고 있을 때
• 프로젝트 내의 로컬 jar 파일이 원격 의존성(Remote Dependency)과 충돌할 때

---

2. 해결 방법 1단계: 의존성 트리 분석 (The Root Cause)

문제를 해결하기 위해 가장 먼저 해야 할 일은 "누가 범인인가"를 찾는 것입니다. 안드로이드 스튜디오의 터미널(Terminal)에서 다음 명령어를 입력하여 의존성 관계도를 확인하세요.

./gradlew :app:dependencies

출력된 트리 구조에서 오류 메시지에 표시된 클래스명을 검색(Ctrl+F)해 보세요. 어떤 라이브러리들이 해당 클래스를 중복해서 가져오고 있는지 확인할 수 있습니다. 보통 implementation으로 추가한 라이브러리들이 하위 의존성으로 같은 것을 물고 있는 경우가 많습니다.

---

3. 해결 방법 2단계: Exclude 구문 사용하기

중복의 원인을 찾았다면, 문제가 되는 특정 라이브러리를 의존성에서 제외(Exclude)시켜야 합니다. 이것이 가장 표준적이고 깔끔한 해결법입니다.

예를 들어, library-a와 library-b가 모두 support-v4를 포함하여 충돌이 발생한다면, 한쪽에서 이를 제외해 줍니다.

dependencies {
    implementation('com.example:library-a:1.0.0') {
        exclude group: 'com.android.support', module: 'support-v4'
    }
    implementation 'com.example:library-b:1.2.0'
}
    

이렇게 하면 library-a가 가져오려던 구버전 혹은 중복된 support-v4는 무시되고, 프로젝트에 명시된 다른 버전을 사용하게 됩니다.

---

4. 해결 방법 3단계: AndroidX 마이그레이션 확인

최근 몇 년 사이 이 오류가 발생하는 가장 흔한 원인은 구형 Support Library와 신형 AndroidX의 혼용입니다. 많은 라이브러리들이 AndroidX로 전환되었지만, 일부 오래된 라이브러리는 여전히 구형 패키지를 요구하기 때문입니다.

이 경우 gradle.properties 파일에 다음 두 줄을 추가하여 빌드 시스템이 자동으로 라이브러리들을 AndroidX로 변환하도록 설정해야 합니다.

android.useAndroidX=true
android.enableJetifier=true
    

Jetifier는 구형 라이브러리의 바이너리를 실시간으로 재작성하여 AndroidX와 호환되게 만들어주는 마법 같은 도구입니다. 대부분의 "Program type already present" 오류는 이 설정만으로 해결되곤 합니다.

---

5. 추가 팁: 캐시 삭제 및 Rebuild

설정을 올바르게 바꿨음에도 불구하고 동일한 에러가 반복된다면, 안드로이드 스튜디오의 캐시가 꼬여있을 가능성이 큽니다. 다음 과정을 수행해 보세요.

1. File > Invalidate Caches / Restart... 클릭
2. Build > Clean Project 실행
3. Build > Rebuild Project 실행

간혹 .gradle 폴더나 build 폴더를 수동으로 삭제한 뒤 다시 빌드하는 것이 도움이 될 때도 있습니다.

---

핵심 요약 정리

💡 해결 체크리스트

• ✅ 1. 원인 분석: ./gradlew dependencies 명령어로 중복 라이브러리 확인
• ✅ 2. 의존성 제외: exclude group: '...', module: '...' 사용하여 중복 제거
• ✅ 3. 현대화: gradle.properties에서 useAndroidX 및 enableJetifier 활성화
• ✅ 4. 로컬 파일 확인: libs 폴더에 직접 넣은 jar 파일과 원격 라이브러리 이름이 겹치는지 확인
• ✅ 5. 최종 수단: 캐시 삭제(Invalidate Caches) 후 재빌드

"Program type already present" 오류는 처음 마주하면 당황스럽지만, 의존성 구조를 이해하고 나면 논리적으로 충분히 해결 가능한 문제입니다. 이 글이 여러분의 즐거운 코딩 생활에 조금이나마 도움이 되었기를 바랍니다!