---
desc: build-toolchain rules for Flutter Android apps in this org
---

# Working on this project

Read [README.md](README.md) before touching anything under `android/`. It is short, and it
is the accumulated cost of two apps that stopped building without their code changing.

The four rules that matter, in the order they get violated:

1. **Never edit `~/.pub-cache`.** Shared between users, unversioned, invisible to git, wiped
   by the next `pub get`. If a plugin needs different build settings, override them from
   `android/build.gradle.kts` (worked example inside, commented out). To undo damage:
   `dart pub cache repair --all`.
2. **Do not guess version numbers.** Flutter's Gradle/AGP/Kotlin/Java floors live in
   `$FLUTTER_ROOT/packages/flutter_tools/gradle/src/main/kotlin/DependencyVersionChecker.kt`
   and `.../lib/src/android/gradle_utils.dart`. Read them. `flutter-android-preflight` does
   it for you and `--fix` applies the result.
3. **Run `flutter-android-preflight .` before debugging a build failure**, and after every
   `flutter upgrade`. Most "Gradle is broken" symptoms are one of its checks.
4. **Do not migrate to Built-in Kotlin yet**, however loudly Flutter warns. On Flutter
   3.47.1 the migration is self-contradictory — AGP 9.1.0 supplies Kotlin 2.2.10, below
   Flutter's own 2.2.20 floor. Keep `android.builtInKotlin=false`.

When a build fails, read the error before changing versions. Climbing the Gradle version
ladder one release at a time produces a different, equally confusing error at each rung and
converges on nothing — the floors are all knowable up front, from the two files above.