Как исправить ошибку Gradle project sync failed в Android Studio?

Ошибка Gradle project sync failed в Android Studio — одна из самых частых проблем, с которой сталкиваются разработчики. Она возникает при открытии проекта, после обновления студии или при смене ветки в Git. Синхронизация падает, и без неё невозможно ни собрать, ни запустить приложение. В этой статье я собрал все основные причины этой неполадки и пошаговые инструкции по их устранению.


Почему возникает ошибка синхронизации Gradle

Причин у ошибки Gradle project sync failed может быть несколько, и все они сводятся к тому, что Android Studio не может корректно связать ваш проект с Gradle-окружением. Чаще всего проблема вызвана одной из следующих ситуаций:

  • Несовместимость версий Gradle, Android Gradle Plugin и Kotlin.
  • Проблемы с доступом в интернет для загрузки зависимостей.
  • Нехватка оперативной памяти, выделенной для Gradle.
  • Отсутствие в локальном SDK требуемой платформы Android.
  • Повреждённый кэш Gradle после обновления.

Шаг 1: Читаем сообщение об ошибке

Первое и самое важное действие — открыть вкладку Build в нижней части окна Android Studio и прочитать текст ошибки. Фраза «Gradle project sync failed» — это лишь общее уведомление, а реальная причина скрыта в деталях. Например:

  • Could not resolve all files for configuration — не удалось скачать зависимости.
  • SdkPlatformNotFoundException: модуль 'app' платформа 'android-29' не найдена — не установлена требуемая версия SDK.
  • Could not determine java version from '17' — версия Gradle несовместима с установленной Java.
  • Kotlin version that is used for building with plugins differs from the one bundled into the IDE — конфликт версий Kotlin.

Точный текст ошибки определяет, какое из описанных ниже решений подойдёт в вашем случае.


Шаг 2: Проверяем совместимость версий

Самая частая причина — несоответствие между Gradle, Android Gradle Plugin (AGP) и Kotlin. Каждая версия AGP требует определённой версии Gradle. Например, AGP 8.2 работает с Gradle 8.2 и выше, а AGP 8.5 — с Gradle 8.7 и выше[reference:0]. Откройте три файла в проекте и сверьте версии:

  1. gradle-wrapper.properties — здесь указана версия Gradle, которую использует проект.
  2. build.gradle.kts (уровень проекта) — здесь задана версия Android Gradle Plugin.
  3. build.gradle.kts (уровень модуля) — здесь указана версия Kotlin.

Вот пример согласованной конфигурации для проекта на Kotlin:

// gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip

// build.gradle.kts (уровень проекта)
plugins {
    id("com.android.application") version "8.7.3" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}

// build.gradle.kts (уровень модуля)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

Если версии не совпадают, приведите их к совместимым значениям и запустите синхронизацию заново.


Шаг 3: Очищаем кэш Gradle и перезапускаем студию

Повреждённый кэш — вторая по частоте причина ошибки. В Android Studio есть встроенный инструмент для его очистки: выберите File → Invalidate Caches, отметьте пункт Clear file system cache and Local History и нажмите Invalidate and Restart[reference:1]. После перезапуска студия переиндексирует проект и пересоздаст кэш.

Если встроенный метод не помог, удалите папку .gradle в корне проекта и глобальный кэш Gradle в вашей домашней директории (~/.gradle/caches на macOS/Linux или C:\Users\ИмяПользователя\.gradle\caches на Windows). Затем снова синхронизируйте проект[reference:2].


Шаг 4: Настраиваем интернет и прокси

Если в ошибке фигурируют слова Connect timeout или Could not resolve, значит Gradle не может скачать зависимости. Попробуйте отключить VPN и проверить, открывается ли сайт dl.google.com в браузере. Если доступ к ресурсам Google заблокирован, можно вручную скачать архив Gradle и указать его локальный путь:

// gradle-wrapper.properties
distributionUrl=file\:/C:/gradle/gradle-8.9-bin.zip

Архив нужной версии загружается с services.gradle.org/distributions и помещается в любую удобную папку[reference:3].

Также проверьте настройки прокси в Android Studio: File → Settings → Appearance & Behavior → System Settings → HTTP Proxy. Если вы не используете прокси, должен быть выбран пункт No proxy. Для проектов за корпоративным прокси может потребоваться указать его адрес и учётные данные.


Шаг 5: Увеличиваем память для Gradle

Ещё одной причиной ошибки Gradle project sync failed может быть нехватка оперативной памяти, выделенной для Gradle. Это особенно актуально для крупных проектов с большим количеством модулей. Откройте файл gradle.properties в корне проекта и найдите строку org.gradle.jvmargs. Если её нет — добавьте:

org.gradle.jvmargs=-Xmx4096M -XX:MaxMetaspaceSize=1024m

Значение -Xmx4096M означает, что Gradle сможет использовать до 4 ГБ оперативной памяти. Для средних проектов этого достаточно, но для крупных можно увеличить до 8 ГБ[reference:4].


Шаг 6: Устанавливаем недостающие версии SDK

Ошибка SdkPlatformNotFoundException означает, что в вашем локальном Android SDK отсутствует платформа, указанная в compileSdk файла build.gradle.kts. Откройте Tools → SDK Manager, перейдите на вкладку SDK Platforms и установите флажок напротив нужной версии Android. Например, для compileSdk = 35 потребуется Android 15.0 (VanillaIceCream)[reference:5].

После установки платформы вернитесь к проекту и нажмите Sync Now.


Шаг 7: Отключаем антивирус для папок проекта

Встроенный антивирус Windows (Microsoft Defender) иногда блокирует файлы Gradle, считая их подозрительными. Это проявляется как ошибка вида Immutable workspace contents have been modified. Добавьте папку проекта и директорию .gradle в исключения антивируса. Для Defender это делается через Параметры → Обновление и безопасность → Безопасность Windows → Защита от вирусов и угроз → Управление настройками → Исключения[reference:6].


Шаг 8: Создаём новый проект и переносим код

Если ни один из предыдущих шагов не помог, проблема может быть в повреждённых файлах конфигурации IDE. Самый радикальный, но надёжный способ — создать новый проект с теми же параметрами (имя пакета, минимальный SDK), а затем скопировать в него папку app/src и содержимое build-файлов из старого проекта. Это гарантированно устранит любые скрытые конфликты в конфигурации[reference:7].


Основные причины и решения в одной таблице

Симптом Причина Решение
Could not resolve dependencies Проблемы с сетью или прокси Проверить интернет, отключить VPN, настроить прокси
SdkPlatformNotFoundException Не установлена требуемая версия SDK Установить нужную платформу через SDK Manager
Kotlin version differs Несовместимость Kotlin и AGP Привести версии к совместимым (см. таблицу совместимости)
Could not determine java version Gradle не поддерживает текущую Java Обновить Gradle или переключить JDK в настройках
Connect timeout Недоступен сервер загрузки Gradle Скачать архив вручную и указать локальный путь
Immutable workspace contents Антивирус блокирует файлы Добавить папки проекта в исключения антивируса

Коротко о главном

  • Всегда начинайте с чтения точного текста ошибки во вкладке Build.
  • Держите версии Gradle, Android Gradle Plugin и Kotlin совместимыми.
  • Периодически очищайте кэш через File → Invalidate Caches.
  • Для Gradle выделяйте не менее 4 ГБ ОЗУ в gradle.properties.
  • При проблемах с сетью скачивайте Gradle вручную и указывайте локальный путь.

Теперь вы знаете, как исправить ошибку Gradle project sync failed в большинстве ситуаций. Сохраните эту статью в закладки — она пригодится вам при каждом обновлении Android Studio или открытии чужого проекта. Если после всех шагов проблема сохраняется, опишите точный текст ошибки на Stack Overflow или в трекере Google Issue Tracker — сообщество разработчиков быстро подскажет решение.

Добавлен: