[해결] Gradle Sync 실패, 알고 보니 안드로이드 스튜디오 버전이 낮았습니다 (AGP 호환표 정리)

얼마 전에 오랜만에 프로젝트를 열었는데 Gradle Sync가 시작하자마자 빨간 줄을 뿜더라고요.

코드는 한 줄도 안 건드렸어요. 어제까지 멀쩡히 빌드되던 프로젝트였고요. 처음엔 캐시 문제인 줄 알고 Invalidate Caches부터 눌렀는데, 재시작해도 똑같은 에러가 나왔어요.

결론부터 말하면 원인은 안드로이드 스튜디오 버전이 낮아서였어요. 프로젝트의 Android Gradle Plugin(AGP) 버전은 올라가 있는데, 제 스튜디오는 그 버전을 열 수 없는 버전이었던 거죠.

이런 에러가 은근히 자주 나요. 저도 예전에 비슷한 걸로 한 번 고생한 적이 있고요. 그래서 이번엔 제대로 정리해두려고 합니다.

에러 메시지는 이렇게 생겼어요

제가 본 메시지는 이런 형태였어요.

The project is using an incompatible version (AGP 9.4.0) of the Android Gradle plugin.
Latest supported version is AGP 9.3.x

지금 다시 보면 답이 다 적혀 있어요. "프로젝트는 AGP 9.4.0을 쓰는데, 이 스튜디오가 지원하는 건 9.3까지다." 그런데 막상 에러가 뜨면 첫 줄만 보고 구글에 복붙부터 하게 되더라고요 ^^

검색해보면 AGP를 내리라는 답변이 꽤 많아요. 급할 땐 그것도 방법이지만, 이 경우엔 스튜디오를 업데이트하는 게 정답이에요. AGP를 내리면 그 버전에 맞춰 올려둔 다른 설정들이 줄줄이 다시 깨질 수 있거든요.

버전 네 개가 서로 물려 있어요

이 문제가 헷갈리는 이유는 버전이 하나가 아니라서예요. 안드로이드 빌드 한 번에 버전 네 개가 맞물려 돌아가요.

Android Studio · AGP · Gradle · JDK, 버전 네 개가 맞물리는 구조

위에서부터 보면 이래요.

• Android Studio가 열 수 있는 AGP 버전에 상한이 있어요.
• AGP는 돌아가려면 최소 몇 버전 이상의 Gradle이 필요해요.
• Gradle은 돌릴 수 있는 JDK 범위가 정해져 있어요.
• JDK는 요즘 AGP 기준으로 17 이상이어야 해요.

에러 메시지는 보통 이 중 한 칸만 가리켜요. 그런데 그 칸을 고치면 바로 아래 칸이 다시 터지는 경우가 많아요. AGP만 올렸더니 Gradle 에러, Gradle을 올렸더니 JDK 에러, 이런 식으로요. 그래서 하나가 터지면 네 개를 한꺼번에 확인하는 게 결국 빨라요.

어느 스튜디오가 어느 AGP까지 여나

공식 문서에 호환표가 있어요. 2026년 9월 기준으로 최근 버전만 추려보면 이래요.

Android Studio별 지원 AGP 범위와 AGP별 필요 Gradle 버전 (2026년 9월 기준)

여기서 눈여겨볼 게 하나 있어요. 같은 Quail이라도 패치 번호에 따라 상한이 달라요. Quail 3까지는 AGP 9.3이 한계고, Quail 4가 되어야 9.4를 열 수 있어요.

"나 최신 스튜디오 쓰는데?" 하고 넘기기 쉬운 부분이에요. 이름만 보면 최신 같은데 패치 한두 개 밀려 있으면 딱 이 에러가 나요. 요즘은 AGP가 거의 매달 올라가다 보니 스튜디오 업데이트 알림을 몇 번 미루면 금방 이렇게 되더라고요.

반대 방향도 있어요. 예전 프로젝트를 최신 스튜디오로 열 때요. 호환표를 보면 최신 스튜디오도 AGP 하한이 있어서, 너무 오래된 프로젝트는 스튜디오가 업그레이드부터 하라고 해요. 이때 나오는 게 AGP Upgrade Assistant고요.

에러 문구로 어느 칸인지 가려내기

제가 겪었거나 자주 보는 세 가지를 정리해봤어요.

에러 문구별 원인과 해결 방법

1. 스튜디오가 낮을 때
"incompatible version ... Latest supported version is" 가 보이면 스튜디오 문제예요. Help → Check for Updates로 올리면 끝나요. 업데이트 알림이 안 뜨면 Settings → Appearance & Behavior → System Settings → Updates에서 채널이 Stable로 돼 있는지 확인해보세요.

2. Gradle이 낮을 때
"Minimum supported Gradle version is ..." 가 보이면 AGP만 올리고 Gradle 래퍼는 그대로인 경우예요. gradle/wrapper/gradle-wrapper.properties의 distributionUrl을 호환표에 맞게 올려주면 돼요. 터미널에서 ./gradlew wrapper --gradle-version 9.6.0처럼 명령으로 바꾸는 게 더 깔끔하고요.

3. JDK가 낮을 때
"requires Java 17 to run" 이 보이면 Gradle이 엉뚱한 JDK로 돌고 있는 거예요. 시스템에 예전 JDK가 깔려 있고 JAVA_HOME이 그쪽을 가리키면 이렇게 돼요. Settings → Build, Execution, Deployment → Build Tools → Gradle에서 Gradle JDK를 스튜디오 내장 JBR로 바꿔주면 대부분 해결돼요.

다시 안 겪으려고 정한 것들

이번 일 겪고 나서 몇 가지를 습관으로 정했어요.

• AGP 올리기 전에 스튜디오부터 올린다. 순서를 거꾸로 하면 이번처럼 프로젝트가 안 열려요.
• AGP를 올릴 땐 Gradle 버전도 같이 본다. 호환표 오른쪽 칸을 확인하는 데 10초면 돼요.
• Gradle JDK는 스튜디오 내장 JBR로 고정한다. 시스템 JDK를 따라가게 두면 PC를 바꿀 때마다 흔들려요.
• 에러 메시지는 끝까지 읽는다. 이게 제일 중요한 것 같아요. 버전 번호가 다 적혀 있어요.

빌드 도구가 똑똑해진 만큼 챙길 버전도 늘어난 거라 어쩔 수 없는 부분이긴 해요. 그래도 코드 한 줄 안 바꿨는데 빌드가 깨지는 건 여전히 기분이 별로네요 ^^

혹시 같은 에러로 헤매고 계시다면, 일단 Help → About부터 열어보세요. 생각보다 답이 거기 있을 때가 많아요.