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 the AppFrameworkInfo.plist may 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 directory

    This 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 version

    Running flutter clean should resolve this. If you have customizations in your xcode project settings you may attempt to reset them with flutter 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"
/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"

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 {
  public void configureFlutterEngine(@NonNull FlutterEngine 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
    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.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

Subscribe to Another Dev's Two Cents

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.