When a Flutter release build crashes at startup in a plugin's Android code while debug works, how can R8 cause it, and how do keep rules fix it?

## What R8 is doing in a Flutter build **R8** is the Android toolchain's code shrinker and optimiser for Java and Kotlin bytecode. It removes classes and members it believes are unused, renames what is left to short names, and optimises the rest. A Flutter app's Android side — the embedding, plugins' Android code, native SDKs they depend on — is JVM bytecode, so R8 applies to it. The Flutter Gradle plugin configures this for you. In release builds it: 1. sets `isMinifyEnabled = true` on the `release` build type (R8 on); 2. sets `isShrinkResources` for apps, removing unused Android resources; 3. adds the Android default `proguard-android-optimize.txt` rules; 4. adds Flutter's own `flutter_proguard_rules.pro` (which, among other things, carries a rule for classes implementing `FlutterPlugin` and suppresses warnings for `io.flutter.plugin.**`); 5. adds `android/app/proguard-rules.pro` **if the file exists**. The `--no-shrink` / `--shrink` option still exists on `flutter build`, but its help text says it has no effect and that code shrinking is always enabled in release builds. **Dart code is not affected.** Your Dart is compiled ahead of time into a native library by the Dart toolchain; R8 never sees it. Dart symbol obfuscation is a separate `--obfuscate` flag. ## Why "works in debug, crashes in release" Debug builds do not run R8, so everything is present under its original name. In release, R8 decides what is used by **static analysis** of bytecode. It cannot see uses that happen by name at run time: - **Reflection** — a JSON library in a native SDK that maps fields by name onto model classes; R8 renames or removes the fields and parsing yields `null` or throws. - **Class loading by name** — `Class.forName("...")` with a string from config. - **JNI** — native C/C++ code calling Java methods by name. - **Serialized or persisted names** — class names written to storage and read back. Typical symptoms in a plant-care app that wraps a Bluetooth soil-sensor SDK through a plugin: `ClassNotFoundException` or `NoSuchMethodError` in logcat at startup, or a platform-channel call returning a map with missing fields — only in `flutter run --release` and store builds. Build-time variant: R8 fails the build reporting **missing classes** referenced by a dependency for an optional feature. The fix there is either adding the missing dependency or a `-dontwarn` rule for the optional package. ## Fixing it Create or edit `android/app/proguard-rules.pro`. The Flutter Gradle plugin picks it up automatically; no Gradle edit is needed. ```proguard # Models the sensor SDK parses by reflection -keep class com.example.soilsensor.model.** { *; } # Optional dependency referenced by the SDK but not used by this app -dontwarn com.example.soilsensor.cloud.** ``` Guidelines: - **Be narrow.** Keep the packages that are reflected on, not the whole SDK, or you lose most of the size benefit. - **Prefer library-provided rules.** Well-maintained Android libraries ship consumer rules that R8 applies automatically; a crash often means an outdated plugin or SDK version whose rules are missing. - **Reproduce locally.** `flutter run --release` runs the same R8 configuration, so you can iterate without a store upload. - **Keep the mapping file.** R8 writes a mapping from obfuscated to original JVM names per build; stack traces from the store are unreadable without the matching file. | Symptom | Likely cause | Fix | |---|---|---| | `ClassNotFoundException` in release only | class loaded by name was removed | `-keep class ...` | | JSON fields `null` in release only | reflected fields renamed | `-keep` the model classes and members | | Build fails listing missing classes | optional dependency not on classpath | add the dependency or `-dontwarn` | | Crash only in Dart stack traces | not R8 (Dart is AOT-compiled) | look at Dart obfuscation or the code itself | ## When a plugin is at fault If the crash is inside a published plugin, check its changelog for fixed ProGuard or R8 rules before adding your own; the plugin should ship consumer rules for its own reflection. Adding app-level rules is the stop-gap, upgrading is the fix.