Как быстро исправлять ошибки Gradle Sync и сборки в Android Studio

Если Gradle Sync или сборка падают — сначала обновите AGP/Gradle, очистите кэш и проверьте Build Output; дальше — пошаговые фиксы для конкретных ошибок.

Быстрые исправления (Top 5)

1. Invalidate Caches: File → Invalidate Caches / Restart. Часто решает 70% проблем.
2. Обновите wrapper:

./gradlew wrapper --gradle-version=8.7
# в gradle/wrapper/gradle-wrapper.properties:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

3. Синхронизация плагина AGP → версию плагина задавайте в project build.gradle:

plugins {
  id 'com.android.application' version '8.5.2' apply false
}

4. Проверьте repositories: в settings.gradle используйте централизованное управление:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories { google(); mavenCentral(); gradlePluginPortal() }
}

5. Очистка кэша и пересборка:

rm -rf ~/.gradle/caches/  # аккуратно
./gradlew clean --refresh-dependencies

Продвинутые ошибки и рабочие решения

• Could not resolve dependency — проверьте репозитории, прокси/VPN и локальный .gradle. Если CI в России тормозит, добавьте региональный mirror (мавен-блок) или временно включите gradle.properties с увеличенным таймаутом.
• Execution failed for task ':app:checkDebugAarMetadata' — конфликт версий библиотек. Принудительно решайте версии в dependencies через force или используйте BOM/Version Catalog.
• DexArchiveMergerException (64k) — включите multidex:

android {
  defaultConfig { multiDexEnabled true }
}
dependencies {
  implementation 'androidx.multidex:multidex:2.0.1'
}

• NDK/JNI на M1/M2 — ставьте совместимую версию NDK через SDK Manager и указывайте ndk.dir в local.properties.

Полная последовательность "убийцы ошибок"

1. Закройте Android Studio.
2. Удалите кэши: rm -rf ~/.gradle/caches/ && rm -rf /.gradle /build
3. В корне проекта: ./gradlew clean --refresh-dependencies --no-daemon
4. Откройте Studio, сделайте Sync Project with Gradle Files, затем Build → Rebuild Project.
5. Если не помогло — проверьте логи на OutOfMemoryError и увеличьте org.gradle.jvmargs в gradle.properties, включите org.gradle.daemon=true.
6. При конфликте AGP/Gradle — обновите до AGP 8.5+ и Gradle 8.7 (в 2026 году это решение для большинства случаев).

Частые ошибки

• "Gradle sync failed" — общий симптом, смотреть стек в Build Output.
• "Minimum supported Gradle version is X.Y.Z" — обновить wrapper.
• "Could not resolve" — репозитории / сетевые проблемы.
• "Aar metadata" / "Version conflict" — выровнять версии зависимостей.
• "DexArchiveMergerException" — включить multidex или оптимизировать R8/proguard.

FAQ

• Q: С чего начать, если sync падает без ясной причины?
  A: Invalidate Caches + restart → обновить wrapper → чистка кэша → sync.
• Q: Как корректно обновлять AGP и Gradle?
  A: Обновляйте Gradle Wrapper, затем в project-level build.gradle укажите версию плагина и синхронизируйте. Тестируйте на ветке, не в main.
• Q: Нужно ли удалять ~/.gradle всегда?
  A: Не всегда — сначала пробуйте clean и --refresh-dependencies; удаление кеша — когда подозреваете повреждение.
• Q: Что делать при сетевых ошибках в CI?
  A: Используйте зеркала, кешируйте зависимости в CI или проксируйте через приватный artifact proxy.

Удачной сборки — систематический подход (логи → обновления → чистка → повтор) экономит часы на дебаге.