Diagnose and fix Flutter build failures, including dependency conflicts, Gradle errors, compilation issues, and platform-specific build problems. Use when builds fail locally or in CI.
Expert guidance for diagnosing and fixing Flutter build failures in Android projects, including dependency conflicts, Gradle errors, and compilation issues.
flutter build apk or flutter build appbundle)Flutter Android builds go through several stages:
flutter pub get)flutter build)Identify which stage is failing to narrow down the issue.
Always try a clean build first:
# Nuclear option - clean everything
flutter clean
cd android
./gradlew clean
cd ..
rm -rf ~/.gradle/caches # Only if really stuck
flutter pub get
flutter build apk --verbose
Look for key error patterns:
Error: Version conflict between dependencies
Diagnosis:
cd android
./gradlew app:dependencies
Solution:
pubspec.yaml - update conflicting dependenciesandroid/app/build.gradle.kts for Android dependency versions^1.0.0 vs >=1.0.0 <2.0.0flutter pub upgrade --major-versions if neededError: Could not find dependency
Solution:
pubspec.yamlflutter pub cache repairError: Gradle version X.X is required
Solution:
cd android && ./gradlew wrapper --gradle-version=8.0android/gradle/wrapper/gradle-wrapper.propertiesjava -versionError: Gradle daemon stopped unexpectedly
Solution:
cd android && ./gradlew --stoprm -rf ~/.gradle/cachesgradle.propertiesandroid/gradle-ci.propertiesWarning: The following Gradle features are deprecated
Solution:
android/build.gradle.kts and android/app/build.gradle.kts./gradlew --warning-mode all for detailsError: Compilation failed: java.lang.UnsupportedClassVersionError
Solution:
java -versionexport JAVA_HOME=/path/to/java17JavaVersion.VERSION_17Error: GC overhead limit exceeded
Solution:
android/gradle.properties:org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g
android/gradle-ci.properties (3GB limit)-XX:+UseParallelGCError: Missing class referenced from: ...
Solution:
android/app/proguard-rules.pro:-keep class com.your.package.** { *; }
-dontwarn com.problematic.library.**
shrinkResources falseError: R8 task failed
Solution:
android.enableR8.fullMode=true--verbose flag to see detailsError: Kotlin compilation failed
Solution:
android/build.gradle.ktsandroid/app/src/main/kotlin/Error: Could not find NDK
Solution:
ANDROID_NDK_HOME environment variablebuild.gradle.ktsError: Duplicate resources
Solution:
android/app/src/main/res/ for duplicatesbuild.gradle.ktsError: Resource not found
Solution:
flutter pub get to regenerateError: Unhandled Exception: MissingPluginException
Solution:
flutter clean && flutter pub get.flutter-plugins-dependenciespubspec.yamlflutter build apk --verboseError: Plugin version incompatible
Solution:
Error: Manifest merger failed
Solution:
android/app/src/main/AndroidManifest.xml<uses-sdk tools:overrideLibrary="conflicting.package" />
tools:replace or tools:merge attributesError: Permission denied
Solution:
AndroidManifest.xmlflutter clean
flutter pub get
flutter build apk --verbose
cd android
./gradlew clean
./gradlew --stop
cd ..
flutter clean
flutter pub get
flutter build apk --verbose
flutter clean
rm -rf ~/.gradle/caches/
rm -rf ~/.pub-cache/
flutter pub get
flutter build apk --verbose
# Check Flutter setup
flutter doctor -v
# Verify Java version
java -version
# Check Gradle dependencies
cd android
./gradlew app:dependencies
# Build with stacktrace
./gradlew assembleRelease --stacktrace --info
# Or with Flutter verbose
flutter build apk --verbose --debug
If builds work but are slow:
android/gradle.propertiesorg.gradle.parallel=trueorg.gradle.workers.max=4org.gradle.jvmargs=-Xmx4gorg.gradle.configuration-cache=trueandroid/gradle-ci.propertiesorg.gradle.workers.max=2org.gradle.jvmargs=-Xmx3gorg.gradle.daemon=falseorg.gradle.configuration-cache=falseflutter doctor -v - all checks pass?java -version)flutter clean && flutter pub getcd android && ./gradlew cleanpubspec.yaml for errorsandroid/app/build.gradle.kts settingsAndroidManifest.xml is valid--verbose# Clean build
flutter clean && flutter pub get && flutter build apk
# Verbose build
flutter build apk --verbose
# Check dependencies
flutter pub outdated
cd android && ./gradlew app:dependencies
# Gradle info
cd android && ./gradlew --version
./gradlew tasks --all
# Fix common issues
dart fix --apply
flutter analyze
# Update dependencies
flutter pub upgrade
# Check Flutter setup
flutter doctor -v
# Test specific build type
flutter build apk --debug
flutter build apk --profile
flutter build apk --release
If after trying all solutions the build still fails:
Document the issue:
Check resources:
Create minimal reproduction:
flutter create test_appBUILD_OPTIMIZATION.md, TROUBLESHOOTING.md