Common Errors for New Flutter Developers: Tips and Fixes
May 16th, 2024
9 min read
Sep 24th, 2024
I started learning Flutter this year to expand into different areas of development.
Because I’m new, I don’t know my way around the ecosystem yet. Some minor setbacks are not unusual whenever I’m coming to a new technology or programming language.
Flutter can be frustrating in the beginning, but once you’re around the bend, it becomes easier to work with.
I’m here to share with you some common errors that kept popping up and how I was able to fix them.
I plan on keeping this list updated as I learn.
Installation problems and fixes
I found that installing manually by downloading a zip file gave me fewer errors than doing the installation via VSCode.
I don’t remember all the details but somehow the PATH didn’t register correctly. Whenever I ran, dart run build_runner build -d
, to generate code, I received errors and I couldn’t figure it out even though flutter doctor -v
gave me all green check marks.
Somewhere along the way, the dart
executable wasn’t in my path and unsure where it exists.
So if you’re starting your journey with Flutter, I suggest installing by downloading the zip file and carefully following the instructions.
Clean and repair cache
When I find that something goes wrong with Flutter, this is usually my first approach. I run these commands in order before I start researching for a solution.
Usually, it’s a hit or miss but it gives me peace-of-mind that Flutter might not be the culprit and it could be something else like Xcode or a misconfigured setting.
If you don’t have a build_runner, you can skip steps 3 & 4.
flutter clean
flutter pub cache repair
dart run build_runner clean
dart run build_runner build -d
flutter pub get
flutter doctor
Cocoapods errors
Cocoapods is a dependency manager used by Xcode and it’s a requirement if you plan to build any apps for Apple.
This section is dedicated to some issues I ran into when working with Flutter.
Cocoapods not installed error
This one was quite frustrating and recurring.
Launching lib/main.dart on iPhone 15 Pro Max in debug mode...
Warning: CocoaPods not installed. Skipping pod install.
CocoaPods is used to retrieve the iOS and macOS platform side's plugin code that responds to your plugin usage on the Dart side.
Without CocoaPods, plugins will not work on iOS or macOS.
For more info, see https://flutter.dev/platform-plugins
To install see https://guides.cocoapods.org/using/getting-started.html#installation for instructions.
CocoaPods not installed or not in valid state.
Error launching application on iPhone 15 Pro Max.
Exited (1).
You can check if Cocoapods is installed by running gem list | grep cocoapods
.
cocoapods (1.15.2)
cocoapods-core (1.15.2)
cocoapods-deintegrate (1.0.5)
cocoapods-downloader (2.1)
cocoapods-plugins (1.0.0)
cocoapods-search (1.0.1)
cocoapods-trunk (1.6.0)
cocoapods-try (1.2.0)
If you see Cocoapods listed there then the issue is not with the installation.
Here are some possible fixes:
-
Restart VSCode. You need to completely close all VSCode instances before opening the text editor again.
-
Reinstall Cocoapods:
- run
sudo gem uninstall cocoapods
. Select all versions. - after uninstall is complete, run
sudo gem install -n /usr/local/bin cocoapods
- run
-
If using a Ruby Version Manager like
rbenv
:- list all available Ruby version
rbenv install -l
- install the latest Ruby version:
rbenv install 3.3.0
- set global to 3.3.0 with
rbenv global 3.3.0
- make sure the
.rbenv/bin
and.rbenv/shims
are available to your PATH - run
gem install bundler
- perform option 2 again
- list all available Ruby version
Cocoapods base configuration
[!] CocoaPods did not set the base configuration of your project because your project already has a custom config set. In order for CocoaPods integration to work at all, please either set the base configurations of the target `Runner` to `Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig` or include the `Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig` in your build configuration (`Flutter/Release.xcconfig`).
To fix this issue, you’ll need to modify two files where you’ll remove the ?
from #include?
statement.
- In
ios/Flutter/Debug.xcconfig
:
#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
#include "Generated.xcconfig"
- In
ios/Flutter/Release.xcconfig
:
You’re going to add an extra #include
here for the profile.xcconfig
#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
#include "Pods/Target Support Files/Pods-Runner/Pods-Runner.profile.xcconfig"
#include "Generated.xcconfig"
Target versions not supported
You might run into this issue when the version of your target platform isn’t supported by a 3rd-party library that you’ve installed.
Here are some examples of what that might look like:
uses-sdk:minSdkVersion 16 cannot be smaller than version 23 declared in library [:audioplayers]
or
warning: The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 11.0, but the range of supported deployment target versions is 16.0 to 17.0. (in target 'firebase_core' from project 'Pods')
What you need to do is modify your targets for each platform you’re deploying to. In my case, for Android and iOS, I edited these two files to set the minSdkVersion
and the platform :ios
.
In android/local.properties
file, add the flutter.minSdkVersion
on a new line and set it to the version you need.
flutter.minSdkVersion=21
For iOS, go to ios/Podfile
file and uncomment where it says, platform :ios, '<version>'
and specify the version.
# Uncomment this line to define a global platform for your project
platform :ios, '16.0'
If you’re deploying to other platforms, say Windows or macOS, you will need to search the internet on how to update those values.
Use —verbose for pod commands
When using pod commands, sometimes the process is running but nothing is showing up in your terminal.
To get some sort of feedback that the process didn’t hang, use the --verbose
flag.
For example, while in the /ios
folder, you can run to update your Podfile.lock:
pod update --verbose
Kotlin requires a newer version
You might see this error when you’re required to use a newer version of Kotlin in your project:
BUILD FAILED in 8s
[!] Your project requires a newer version of the Kotlin Gradle plugin.
Find the latest version on https://kotlinlang.org/docs/gradle.html#plugin-and-versions, then update project/android/build.gradle:
ext.kotlin_version = '<latest-version>'
Exception: Gradle task assembleDebug failed with exit code 1
To find out where you can update your kotlin_version
, you’ll have to go to /android/settings.gradle
in your project.
Find the plugins
config and update the org.jetbrains.kotlin.android
field with a higher version that’s listed in the error message above.
plugins {
id "dev.flutter.flutter-plugin-loader" version "1.0.0"
id "com.android.application" version "7.3.0" apply false
id "org.jetbrains.kotlin.android" version "2.0.0" apply false
}
Launch the simulator from VS Code
This one was a bit tricky. When developing for Flutter in VSCode, you’ll be using the debugger tool. When you start the debugging tool to launch your Flutter app, the device will often change.
Sometimes it will launch on my physical iPhone. Sometimes it will launch for my macOS. Neither of which I want since I only want to run an iOS simulator.
My approach to this is to use the Flutter: Launch Emulator
from the Command Palette to launch the simulator separately, and then run the debug tool.
To do this, open the Command Palette by using the shortcut, (⌘ + Shift + P).
Begin typing Flutter and you’ll see a list of options you can choose from. When you select Flutter: Launch Emulator
, it will show you all the available simulators that you’ve installed on your machine.
Select one and it should open.
If not, then you may have these next set of issues.
Unable to boot the simulator
This pops up for whatever reason. Maybe I tried to do something with Xcode and broke my simulator.
But no matter what I did, restarting VSCode, uninstalling/reinstalling the simulator, nothing would work.
That is until I found a solution by deleting the Xcode caches.
You need to go to your “System Settings > General > Storage > Developer” and click on the “i” icon button. You should see the following page.
Select “Xcode Caches”, click “Delete…” and continue with the prompt.
From there you should be able to boot your simulator again.
But you might encounter another error when the simulator has booted.
Springboard quit unexpectedly
Another popup that might show up that something went wrong. This time it has something to do with Springboard.
Maybe this issue stemmed from deleting the Xcode cache but I would never know.
A quick internet search tells me that Springboard is the application that manages the home screen for iOS devices.
Not liking the sound of that, I searched for a fix and the only thing that worked for me was to delete Xcode entirely and install it fresh.
It was a hassle but it worked and was something I could do easily since every conversation about the error was way above my technical knowledge.
Rename App ID / Bundle ID
Every app deployed to a platform has a unique App ID. In iOS terms, it’s called the Bundle ID. These unique names are usually reversed in the manner of a domain name.
These App IDs must be unique because this is how the platform identifies your app in their App Store. Whether that be the App Store, Google Play Store, etc. you’ll need to keep them unique and that’s why reversed domain names are standard practice.
For example, billyle.dev
becomes dev.billyle
as my App ID.
When you create a new Flutter project either by the command line or by VSCode, it will default the name of your App ID to be com.example.<YOUR_PROJECT_NAME>
.
I don’t like seeing the “example” in there and it’s not a real representation of what I’m creating.
Instead, when starting a new Flutter project use this command and replace com.yourdomain
and app_name
to your liking.
flutter create --org com.yourdomain app_name
This will then create the App ID for you with com.yourdomain.app_name
.
A thing I am starting to do is replace app_name
with specific platform names like ios
and android
to keep things organized but you don’t need to do this.
If you find that you’re knee-deep in an existing project but your App ID still contains the com.example
name, you can use this rename-cli to rename your App ID.
The instructions are straightforward to use.
Additional resources
- Flutter tips and tricks from Vandad.
Keeping this updated
There you have it. This is my current list of common errors and tips when developing in Flutter.
I hope it helps you on your journey to becoming a Flutter Developer.
I plan to keep this list updated every once in a while when I encounter a new issue so check back every few months.
With that, thanks for reading and I hope you have a good one.