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.
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
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!