Последняя строка `BUILD FAILED` почти бесполезна. В React Native одна ошибка конфигурации создаёт десятки вторичных: не найден plugin, не запустился Codegen, не скомпилировался Kotlin, пропали generated sources. Ищите первую задачу, которая упала, и первый блок `Caused by`.
Перед правкой зафиксируйте toolchain. React Native Gradle Plugin устанавливается вместе с `react-native`, настраивает зависимости, repositories, bundling, Hermes и Codegen. Если `node_modules`, settings plugin и версия RN не образуют один комплект, обновление AGP в одиночку не поможет.
Снимок окружения воспроизводит половину ошибок
node --version
npx react-native info
cd android
./gradlew --version
./gradlew :app:assembleDebug --stacktrace --warning-mode all
# Windows PowerShell/cmd:
gradlew.bat --version
gradlew.bat :app:assembleDebug --stacktrace --warning-mode all`./gradlew` использует wrapper проекта; системный `gradle` может быть другой версии. В выводе `--version` смотрите Gradle и JVM. Android указывает: JDK, запускающий Gradle, должен соответствовать требованиям AGP; например, ветки AGP 8.x требуют JDK 17. Точное соответствие берут из release notes используемой версии, а не из случайной статьи.
Фаза падения указывает владельца настройки
| Фаза/задача | Типичная причина | Первый файл для проверки |
|---|---|---|
| settings/pluginManagement | не найден RNGP/includeBuild | android/settings.gradle |
| configuration | AGP/Gradle/JDK несовместимы | wrapper + top-level build.gradle |
| dependency resolution | repository/версия native module | dependencyInsight/lockfile |
| generateCodegenArtifacts | schema или пакет не поддержан | package.json и library config |
| compileKotlin/Java | API/target/toolchain mismatch | первая исходная ошибка |
| merge/packaging | manifest/resource/duplicate class | merged manifest/dependency graph |
Community Template — контроль, а не рецепт обновить всё
Создайте временный пустой проект той же версии React Native или откройте соответствующий Community Template. Сравните `settings.gradle`, верхний `build.gradle`, `gradle-wrapper.properties`, plugin application и блок `react`. Текущий RN использует settings plugin для autolinking и отдельный React Native Gradle Plugin; старые фрагменты из прошлых поколений могут конфликтовать.
- Не копируйте номера AGP и Gradle из latest template в старую RN-ветку.
- Не указывайте вручную версию react-android, если ею должен управлять RNGP.
- Проверьте относительный путь к node_modules в monorepo.
- Сверьте package manager lockfile и реально установленную версию @react-native/gradle-plugin.
- Сохраните diff конфигурации перед автоматическим upgrade.
Локальная сборка и CI обязаны использовать одну матрицу
Android Studio может запускать Gradle bundled JDK, терминал — JAVA_HOME, а CI — JDK из container image. Поэтому «на моём компьютере работает» проверяют сравнением `./gradlew --version`. Версии Node, package manager и Android SDK/NDK также фиксируют в build log. Секреты подписи не печатают.
| Различие | Признак | Исправление |
|---|---|---|
| JDK | unsupported class/AGP requires Java | единый Gradle JDK/toolchain |
| Node/node_modules | plugin path/codegen missing | lockfile + deterministic install |
| SDK/NDK | platform/side-by-side NDK not found | явная версия и CI install |
| architecture flags | CMake/ABI failure | согласовать reactNativeArchitectures |
| case-sensitive FS | локально есть, Linux CI нет | исправить регистр путей/import |
Clean полезен только после объяснения причины
`clean` удаляет outputs, но не исправляет несовместимость версий. Удаление всех Gradle caches заставляет заново скачивать зависимости и маскирует intermittent repository failure. Сначала воспроизведите ошибку, сохраните dependency graph и stacktrace; затем удаляйте конкретный build directory или повреждённый module cache с возможностью повторить исходный тест.
Минимальный upgrade идёт по одному измерению
- Зафиксировать чистую ветку, lockfile и текущую ошибку Debug/Release.
- Сверить RN-конфигурацию с template той же версии.
- Привести JDK к требованиям текущего AGP и повторить wrapper build.
- Исправить первую фазу, не меняя одновременно все native modules.
- Запустить assembleDebug и release bundle без ключей публикации.
- Повторить в CI с теми же версиями Node/JDK/SDK.
- Только затем обновлять следующий компонент матрицы и сохранять diff.
Для диагностики нужны package.json/lockfile, четыре Gradle-файла без signing secrets, `npx react-native info`, `gradlew --version` и первый stacktrace block. Не присылайте keystore, пароли или полный env. Исправление завершено, когда wrapper воспроизводимо собирает Debug и Release локально и на чистом CI runner.