A Flutter build failure checklist
I've been working with flutter for a while now and I've run into my share of build problems. These tend to happen most frequently when building production versions of my application or following an upgrade to new flutter versions.
I've found it helpful to keep track of issues I've encountered as a reference to avoid having to solve issues I've already encountered in the past and I'm opening this up to others in hopes that it helps save as much time as I've lost working through these issues.
I originally titled this as A flutter iOS build failure checklist as I tend to experience more issues building iOS however i've since expanded the post to include Android issues as well.
Before debugging build issues it's typically helpful to start by peforming a clean
$ flutter clean
If that doesn't work a deep clean which clears the xcode and flutter build cache may help.
$ rm -rf $HOME/Library/Developer/Xcode/DerivedData/*
$ rm -rf $HOME/Library/Flutter/bin/cache/*
$ rm -rf app/ios/Flutter/App.framework ios/Flutter/Flutter.framework
$ rm -rf app/build
$ rm -rf app/.packages
$ rm -rf app/.flutter-plugins
I usually follow this up with a pod install in the iOS project to update necessary dependencies.
If this doesn't work then it's time to roll up your sleeves and really dive into the issue. This is a collection that I've found that I frequently run into recently presented in no particular order.
-
When uploading to the App Store, you get
"Invalid Bundle. The bundle Runner.app/Frameworks/App.framework does not support the minimum OS Version specified in the Info.plist."This may be the result of setting a minimum version in your
Podfile. Updating the apps minimum OS version in theAppFrameworkInfo.plistmay resolve the issue.You may also need to update your iOS deployment target to match.
-
Attempting to build your iOS bundle fails with a clean build with the error
.../Release-iphoneos/Runner.build/Script-66F40DDC22E81E8000FC45EE.sh: line 3: /.../actions-runner/_work/yourapp/yourapp/app/ios/Pods/Fabric/run: No such file or directoryThis is caused by the Flutter Firebase plugin's update to Crashlytics, you will need to migrate the integration by following instructions in the migration guide.
-
Attempting to build an iOS bundle fails with
error: Runner.app/Info.plist does not exist. The Flutter "Thin Binary" build phase must run after "Copy Bundle Resources".after upgrading your flutter versionRunning
flutter cleanshould resolve this. If you have customizations in your xcode project settings you may attempt to reset them withflutter create -i swift .then reapply your customizations. -
Attempting to build your app results in similar errors building protobufs for flutter.
/Users/user/Developer/yourapp/app/ios/Pods/Protobuf/objectivec/GPBUtilities.h:34:9: warning: double-quoted include "GPBMessage.h" in framework header, expected angle-bracketed instead [-Wquoted-include-in-framework-header]
#import "GPBMessage.h"
^~~~~~~~~~~~~~
<GPBMessage.h>
/Users/user/Developer/yourapp/app/ios/Pods/Protobuf/objectivec/GPBUtilities.h:35:9: warning: double-quoted include "GPBRuntimeTypes.h" in framework header, expected angle-bracketed instead [-Wquoted-include-in-framework-header]
#import "GPBRuntimeTypes.h"
^~~~~~~~~~~~~~~~~~~
<GPBRuntimeTypes.h>
This was allegedly the result of a bug introduced in cocoapods. Updating to the latest version sudo gem install cocoapods should resolve the issue. If you have a Gemfile or Gemfile.lock those would need to be updated as well with bundle update.
- Attempting to build your app after upgrading your flutter version results in an error message similar to the following.
Launching lib/main.dart on iPhone 11 Pro Max in debug mode...
Warning: Podfile is out of date
This can cause a mismatched version of Flutter to be embedded in your app, which may result in App Store submission rejection or crashes.
If you have local Podfile edits you would like to keep, see https://github.com/flutter/flutter/issues/24641 for instructions.
To regenerate the Podfile, run:
rm ios/Podfile
Running Xcode build...
Xcode build done. 7,8s
Failed to build iOS app
Error output from Xcode build:
↳
** BUILD FAILED **
Xcode's output:
↳
/Users/user/developer/flutter/.pub-cache/hosted/pub.dartlang.org/cloud_firestore-0.12.11/ios/Classes/CloudFirestorePlugin.m:155:24: error: no visible @interface for 'FIRQuery' declares the selector 'queryWhereField:arrayContainsAny:'
query = [query queryWhereField:fieldName arrayContainsAny:value];
This may be because your Podfile is out of date. Performing a clean and deleting your Podfile will allow the flutter build process to regenerate one.
flutter clean
rm -Rf ios/Pods
rm -Rf ios/.symlinks
rm -Rf ios/Flutter/Flutter.framework
rm -Rf ios/Flutter/Flutter.podspec
rm ios/Podfile
flutter build
- Your app freezes on the splash screen or crashes on launch on Android with the following error/stacktrace
E/flutter (13140): [ERROR:flutter/lib/ui/ui_dart_state.cc(177)] Unhandled Exception: MissingPluginException(No implementation found for method Firebase#initializeCore on channel plugins.flutter.io/firebase_core)
E/flutter (13140): #0 MethodChannel._invokeMethod (package:flutter/src/services/platform_channel.dart:160)
This seems to be caused by the Firebase plugin failing to find methods it needs in order to startup. This may be caused by improper proguard retention policies and not having GeneratedPluginRegistrant.registerWith set in your activity
public class MainActivity extends FlutterActivity {
@Override
public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
GeneratedPluginRegistrant.registerWith(flutterEngine);
}
}
For proguard rules, I recommend having at least the following
## Flutter wrapper
-keep class io.flutter.** { *; }
## Android internals
-keep class androidx.lifecycle.** { *; }
-keep class com.google.android.** { *; }
However, these should be customized for your usecase.
- Updating or changing packages result in the error
fatal error: 'Flutter/Flutter.h' file not found
In file included from
/Users/example_path/.pub-cache/hosted/pub.dartlang.org/shared_preferences-0.5.12+4/ios/Classes/FLTSharedPreferencesPlugin.m:5:
/Users/example_path/.pub-cache/hosted/pub.dartlang.org/shared_preferences-0.5.12+4/ios/Classes/FLTSharedPreferencesPlugin.h:5:9:
fatal error: 'Flutter/Flutter.h' file not found
#import <Flutter/Flutter.h>
^~~~~~~~~~~~~~~~~~~
1 error generated.
In file included from
/Users/example_path/.pub-cache/hosted/pub.dartlang.org/path_provider-1.6.24/ios/Classes/FLTPathProviderPlugin.m:5:
/Users/example_path/.pub-cache/hosted/pub.dartlang.org/path_provider-1.6.24/ios/Classes/FLTPathProviderPlugin.h:5:9: fatal error:
'Flutter/Flutter.h' file not found
#import <Flutter/Flutter.h>
^~~~~~~~~~~~~~~~~~~
1 error generated.
This seems to be the result of a badly generated podspec or symlinks used not being updated correctly. What worked for me in this case was removing my ios/Flutter/Flutter.podspec file before building as described in this issue.
$ rm ios/Flutter/Flutter.podspec
$ flutter clean