Flutter Troubleshooting Guide

We often run into problems after updating some dependencies, flutter itself, or changing some setup configuration. Various things might go wrong and block you from building a flutter app while your colleagues don’t have any problem.

With the following steps, so far we could fix most of the problems building and running a flutter application.

A word of caution – as always, don’t copy blindly commands into your terminal you find online. Try to understand what they are doing and read about them before executing them. Otherwise, you might lose precious data on your computer.

Validate your Flutter installation

If you usually don’t build the project because you are working as QA or backend engineer, you should validate that you have the correct Flutter version installed first.

Make sure the correct Flutter version is installed

Check that you are on the correct Flutter channel:

$ flutter channel stable|beta|dev|master

Afterward update to the latest version:

$ flutter upgrade --force

Or you need a specific Flutter version to build the project downgrade a specific version:

$ flutter downgrade v1.22.6

Run Flutter Doctor

The first thing afterward should be checking if something is wrong with your flutter setup. With the following command you can check for common setup issues:

$ flutter doctor

Restart Android Studio or Visual Studio Code

“Did you try turning it off and on again?” — sounds stupid but helps very often. Something the IDEs just don’t realize that something has changed, e.g. after switching branch. It might help just restarting your IDE and trying again.

Cleaning

This command is most of the time enough to get you going again.

$ flutter clean

If that doesn’t help, you can also try cleaning manually.

$ rm -rf build
$ rm -rf .packages 
$ rm -rf .flutter-plugins

everything seems broken after running flutter clean

CocoaPods and Xcode

When building for iOS, we found that often problems with CocoaPods. Sometimes you need to update the pod repos, sometimes re-creating the Xcode pods project. The following does everything:

$ pod cache clean --all
$ rm -rf ios/.symlinks
$ rm -rf ios/Podfile.lock 
$ rm -rf ios/Pods/
$ pod repo update

There is also our friend derived data:

$ rm -rf ~/Library/Developer/Xcode/DerivedData/*

Generate Auto-Generated Code

If you use a database library like floor, that uses build runner, use the following command to re-generate the dart source code:

$ flutter packages pub run build_runner build --delete-conflicting-outputs

Another thing might be to re-generate localizations if you use something like intl utils. For intl utils, use the following command:

$ flutter pub run intl_utils:generate

There are many other tools and libraries out there. And the project you are trying to run might use some of them. Please check your project and documentation on how to generate code for those libraries and tools.

Repair the pub cache

After updating flutter, we found that sometimes you need to repair your pub cache. Use the following command for this:

$ flutter pub cache repair

Kill rogue Dart processes

Unfortunately, sometimes a dart process will stick around in the background blocking you from building your flutter project. They might do things like generating localisations or creating auto-generated code and hang doing so or run with the wrong input or configuration.

So, looking for unwanted dart processes and killing them might help:

$ killall -9 dart

Restart your computer

If all above doesn’t help, restart your computer. A few times this resolved our build issues. There might be better ways of detecting and fixing issues, but as a last resort, this can work.

Thanks for reading and checking out this article. Hopefully, it helped you resolve the issues you were facing!