Flutter App Works in Debug but Fails in Release

August 28, 2026·4 min read·Advanced

The app runs correctly with flutter run (debug mode) but crashes, behaves incorrectly, or fails to build entirely in release mode (flutter build apk --release, flutter build ipa, or flutter run --release).

androidiosflutterandroidiosreleaser8

The Problem

Symptoms

•App works perfectly via flutter run but crashes immediately in a release build
•A feature depending on reflection or dynamic class names stops working only in release
•Release build succeeds but a network call, Firebase feature, or plugin fails at runtime

Why This Happens

•R8/ProGuard (Android's code shrinker, enabled by default in release builds) removes or renames a class accessed via reflection
•Environment-specific configuration (API keys, base URLs) that differs between debug and release builds
•Firebase or other native SDK configuration files not correctly included in the release build variant
•Code that branches on kDebugMode/kReleaseMode and was never tested in the release path
•Signing configuration issues specific to release builds

Quick Fix

Run flutter run --release locally so you can see the actual crash log, instead of debugging blind from user reports.

How to Fix It

1. Reproduce locally with flutter run --release

flutter run --release This gives you a live, attached release build with crash output in the terminal — far faster than reasoning from a report with no logs.

2. Check for R8/ProGuard-related crashes

If the crash mentions a ClassNotFoundException or a missing method only in release, a plugin relying on reflection was stripped. Add a -keep rule for the affected class in android/app/proguard-rules.pro, following that plugin's documented ProGuard rules.

3. Diff debug vs release configuration

Check for code branching on kDebugMode/kReleaseMode, different .env/build-flavor files, and confirm the same Firebase config files and API endpoints are used in both build variants.

4. Check native crash logs, not just Flutter's

For Android, run adb logcat while the release build is running to see native-level exceptions. For iOS, use Xcode's device console or Instruments.

Common Mistakes

×Debugging only from crash reports without ever running flutter run --release locally
×Disabling code shrinking entirely instead of adding a targeted keep rule
×Assuming a release-only crash is a Flutter bug rather than checking native logs first

How to Verify the Fix

1.Confirm the release build now runs the previously-failing path successfully via flutter run --release
2.Test on a real device, not just an emulator
3.If a ProGuard/R8 keep rule was added, confirm app size didn't unexpectedly balloon

ShareX LinkedIn