Android Studio를 사용하는 개발자들이 코드를 컴파일하거나 Android 기기(실제 기기 또는 에뮬레이터)에서 실행할 때 'Gradle Project Sync Failed(Gradle 프로젝트 동기화 실패)' 오류 메시지를 경험하는 경우가 많습니다. Gradle Sync는 Android Studio 프로젝트와 연결된 build.gradle 파일의 모든 종속성을 확인하고, 아직 다운로드되지 않은 경우 지정된 버전을 다운로드하는 것이 주요 역할인 Gradle 작업입니다.
이 오류 메시지는 다양한 원인으로 발생할 수 있습니다. 단순한 인터넷 연결 문제부터 Gradle 컴파일 자체가 작동하지 않는 복잡한 문제까지 여러 상황이 있을 수 있습니다. 이 글에서는 이 문제가 발생하는 모든 원인을 살펴본 후, 단계별 해결 방법을 안내해 드리겠습니다.
Android Studio에서 'Gradle 프로젝트 동기화 실패' 오류가 발생하는 원인
앞서 언급했듯이 Gradle 프로젝트가 컴파일 또는 동기화에 실패하는 데에는 여러 가지 이유가 있습니다. 주요 원인은 다음과 같습니다(모든 항목이 해당되는 것은 아닙니다):
- 불안정한 인터넷 연결: Gradle은 프로젝트 실행에 필요한 누락된 버전들을 모두 다운로드하기 때문에, 인터넷 연결이 정상적이지 않으면 작업이 실패할 수 있습니다.
- Gradle 컴파일러 문제: Gradle 컴파일러가 제대로 작동하지 않는 경우가 있습니다. 이때 Gradle을 수동으로 로드하여 문제가 해결되는지 확인해 볼 수 있습니다.
- Android Studio의 손상된 캐시: Android Studio는 정상적인 작동을 위해 컴퓨터의 캐시를 사용합니다. 캐시가 손상되면 Gradle을 포함한 여러 모듈에서 문제가 발생할 수 있습니다.
- 누락된 파일: Gradle 실행에 필요한 파일이 누락된 경우도 있습니다. 해당 파일을 설치하면 문제가 즉시 해결됩니다.
- 프록시 서버: 프록시 서버 사용이 점점 보편화되고 있지만, 프록시 환경에서 Gradle 동기화가 제대로 되지 않는 사례도 확인되었습니다. 프록시 서버를 비활성화하면 문제가 해결됩니다.
해결 방법을 시작하기 전에 현재 프로젝트를 반드시 백업하세요. 파일을 저장하고 만약을 대비해 다른 곳에도 사본을 만들어 두는 것이 좋습니다. 또한 컴퓨터에서 관리자 권한으로 로그인되어 있는지 확인하세요.
해결 방법 1: 인터넷 연결 확인
Gradle이 제대로 작동하려면 컴퓨터에 정상적인 인터넷 연결이 필요합니다. Gradle의 주요 역할이 인터넷에서 필요한 버전들을 다운로드하는 것이기 때문에, 안정적인 인터넷 연결은 필수입니다. 같은 네트워크에 다른 기기를 연결해 보면 연결 상태를 점검할 수 있습니다. 인터넷 연결에 문제가 없다는 것이 확실하다면 다른 해결 방법으로 넘어가세요.
해결 방법 2: 프록시 서버 비활성화
프록시 서버는 조직이나 기관에서 대역폭을 효율적으로 활용하고 사용자들에게 더 나은 인터넷 접속 환경을 제공하기 위해 점점 더 널리 사용되고 있습니다. 하지만 프록시 서버에는 한계가 있는데, 그중 하나가 모듈 동기화가 제대로 작동하지 않는 문제입니다. Gradle도 예외가 아닙니다. 프록시 서버를 사용하고 있지 않은지 확인하는 방법은 다음과 같습니다.
- Windows + R 키를 누르고 실행 창에 "inetcpl.cpl"을 입력한 후 Enter 키를 누릅니다.
- 인터넷 속성(Internet Properties) 창이 열리면 연결(Connections) 탭을 클릭한 후 LAN 설정(LAN settings)을 클릭합니다.
- 프록시 서버를 사용 중이라면 해당 필드에 체크 표시와 함께 세부 정보가 입력되어 있을 것입니다. 활성화된 프록시 서버 설정이 있다면 체크를 해제하세요. 그런 다음 Android Studio를 재시작하고 문제가 해결되었는지 확인합니다.
해결 방법 3: 누락된 구성 요소 설치
더 복잡한 기술적 방법을 시도하기 전에, Gradle 동기화에 필요한 모듈이 누락되어 있지 않은지 먼저 확인해야 합니다. Gradle은 독립적으로 작동하는 도구가 아니며, 정상적으로 작동하려면 다른 서비스들도 함께 필요합니다.
Gradle 동기화를 시도할 때 오류 메시지가 나타나면, 오류 아래에 'Install missing platform(s) and sync project(누락된 플랫폼 설치 및 프로젝트 동기화)'라는 제목의 하이퍼링크가 있는지 확인하세요. 링크를 클릭하면 Android Studio가 다운로드 프로세스를 시작하고 누락된 모든 항목을 설치합니다. 이후 프로젝트를 다시 동기화하여 문제가 해결되는지 확인해 보세요.
해결 방법 4: 로컬 Gradle 배포판 사용
프로젝트를 빌드하면 Gradle이 활성화되면서 최신 온라인 배포판에 연결하여 필요한 모듈이나 버전을 다운로드합니다. 온라인 배포판이 예상대로 작동하지 않아 Gradle 동기화에 실패하는 사례가 여러 건 확인되었습니다. 이 문제에 대한 대안으로 Gradle 배포판을 직접 다운로드하여 사용하는 방법이 있습니다. 아래 단계를 따라 해보세요:
- Gradle 공식 릴리스 웹사이트에서 최신 버전의 Gradle을 다운로드합니다.
- 다운로드 후 모든 파일을 접근 가능한 폴더에 압축 해제합니다.
- Android Studio를 실행하고 File > Settings > Build, Execution, Deployment > Gradle로 이동합니다.
- Local Gradle Distribution(로컬 Gradle 배포) 옵션을 선택합니다. 그리고 Gradle home 항목에 방금 압축을 해제한 폴더의 경로를 지정합니다.
참고: 전역 Gradle 설정(Global Gradle Settings)에서 오프라인 작업(Offline work)을 사용 중이라면 해당 옵션의 체크를 해제하세요.
- 이제 프로젝트를 빌드하고 Gradle이 정상적으로 동기화되는지 확인합니다. 새 프로젝트를 생성할 때마다 이 단계를 반복해야 할 수 있습니다.
해결 방법 5: GPU 디버거 활성화
GPU 디버거를 사용하면 OpenGL ES 애플리케이션을 디버그하고 분석할 수 있습니다. GPU 상태를 검사하고 렌더링 결과의 원인을 파악하는 등 여러 기능을 제공합니다. 일부 Gradle 빌드 환경에서는 이 기능이 활성화되지 않는 시스템 버그가 존재합니다. 이 해결 방법에서는 모듈을 강제로 새로 고침하여 해당 구성 요소를 설치해 보겠습니다.
- Tools를 클릭한 후 Android > SDK Manager를 선택합니다.
- SDK Tools 탭을 클릭한 후 Android SDK Build-Tools 옵션의 체크를 해제합니다. 약 5초간 기다린 후 다시 옵션을 활성화합니다.
- 목록이 새로 고침되고 항목이 채워질 때까지 잠시 기다립니다.
- 새 항목이 표시되면 목록을 살펴보고 GPU Debugging Tools 옵션을 체크합니다. 완료되면 OK를 누릅니다.
이제 해당 도구들이 Android Studio에 다운로드되며, 문제없이 Gradle을 정상적으로 동기화할 수 있게 됩니다.
해결 방법 6: 캐시 새로 고침
Microsoft Windows를 포함한 모든 애플리케이션은 원활한 실행을 위해 곳곳에 캐시를 사용합니다. 캐시는 애플리케이션이 환경설정이나 임시 데이터를 저장해 두었다가 나중에 불러올 수 있는 임시 저장소 역할을 합니다. 이 캐시가 손상되면 Gradle 빌드 프로세스가 중단될 수 있다는 것을 확인했습니다. 이 해결 방법에서는 전체 캐시를 새로 고치고, 기존 Gradle 파일을 삭제한 후 Android Studio를 재시작하여 문제가 해결되는지 확인해 보겠습니다.
- File 메뉴로 이동하여 Invalidate cache/Restart(캐시 무효화/재시작)를 클릭합니다.
- 프로세스가 완료되면 Android Studio를 완전히 종료합니다.
- Android Studio 설치 디렉터리의 .gradle 폴더로 이동합니다. 이 폴더를 다른 위치로 잘라내기/붙여넣기 하거나 이름을 변경하세요.
이렇게 하면 Android Studio가 Gradle 파일에 접근하려고 할 때 파일이 존재하지 않음을 감지하고 전체를 다시 다운로드하게 됩니다. - Android Studio를 재시작하고 Gradle 동기화를 다시 시도합니다. 이후 문제가 해결되었는지 확인하세요.