Solving Flutter’s Gradle Issues

Common Gradle Issues in Flutter

Many people come from different backgrounds to Flutter, and not everyone is familiar with Gradle.

Usually, when you want to create Flutter apps, you want to deploy them to Android, and Gradle can be a bit of a pain.

Luckily, I have an Android background, so I can navigate most of the issues without problems, but others might not be so lucky.

To make your life easier, I will try to summarize the most common issues and how to solve them.

This is not an exhaustive list, but it should cover most of the issues you will encounter.

We will go from the most obvious solutions to more complex ones.

Flutter Clean

Before you try anything else, you should always try to run flutter clean. It solves many issues, especially when you are switching branches or updating dependencies.

flutter clean
flutter pub get

# if you are using build_runner
dart run build_runner build -d

Flutter Doctor

If you are still having issues, you should run flutter doctor to see if there are any problems with your Flutter installation.

flutter doctor -v # verbose output

Flutter is usually verbose if there are any obvious issues, so you should be able to see what is wrong.

Most common are:

• Missing Android SDK
• Missing environment variables
• Missing license agreements

The simplest thing to do here is to install Android Studio and try to run the app from it. Just installing it should fix most of the issues.

Or you can open the Android Studio and Flutter’s Android project and try to run it from there. It will usually give you more information about the issue.

Java is not Available for License Agreements

You can agree to the license agreements by going to the Android Studio SDK Manager and installing the missing components. During the installation, it will prompt you to accept the license agreements.

However, if you are not using Android Studio, you can do it from the command line.

flutter doctor --android-licenses

This fails if Java is not installed, not available in your PATH or if the version is not compatible.

To agree to the license agreements, you need to have Java installed and available in your PATH.

If you are on macOS or Linux, I recommend using SDKMAN to manage your Java versions. It makes it easy to switch between different versions of Java.

On Windows, you should use the official distribution from Oracle or use WinGet to install it.

You can use these approaches to install Java and also Gradle, which you can then run in the terminal.

Missing JAVA_HOME

This is mostly related to the previous issue, but it can also happen if you have multiple Java versions installed and the JAVA_HOME environment variable is not set correctly.

Flutter looks for the JAVA_HOME environment variable to find the Java installation, and if it is not set, it will fail with an error.

If you have a custom path for the Java installation, you can set Flutter to use it by setting the JAVA_HOME environment variable or by using following command:

flutter config --jdk-dir <path-to-jdk>

Outdated Gradle Version and Android Gradle Plugin

Flutter evolves quickly, and Flutter changes the preferred Gradle version and Android Gradle Plugin version quite often. Almost every major release of Flutter changes the Gradle version and Android Gradle Plugin version.

You can check the current version in the android/gradle/wrapper/gradle-wrapper.properties file.

distributionUrl=https\://services.gradle.org/distributions/gradle-x.x.x-bin.zip

You can also check the current version of the Android Gradle Plugin in the android/build.gradle file or android/settings.gradle.

Old imperative style:

buildscript {
    ext.kotlin_version = '1.x.x' // preferred Kotlin version
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:x.x.x' // use the recommended version
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

Newer declarative style:

plugins {
    id 'com.android.application' version 'x.x.x' apply false // use the recommended version
    id 'org.jetbrains.kotlin.android' version 'x.x.x' apply false // use the recommended version
    id 'dev.flutter.flutter-gradle-plugin'
}

Kotlin version is not related to the Gradle version, but it is recommended to use the latest version of Kotlin that is compatible with the Android Gradle Plugin.

Which Version to Use?

Flutter lags behind the latest Gradle and Android Gradle Plugin versions, so you should always use the version that is recommended by Flutter.

When a major Flutter version is released, the version of the Gradle and Android Gradle Plugin is usually mentioned in the release notes of the Flutter version.

The most foolproof way to find out the correct version is to create new Flutter project and check all the files in the android directory. The new project will always use the recommended versions.

Unfortunately, I have not found any official documentation that lists the recommended versions for each Flutter version, so you will have to rely on the release notes or create a new project. If you have found such documentation, please let me know, and I will update this article.

Another way to check the compatible versions is to check Gradle compatibility matrix here.

Updating Target SDK Version

You should always target the latest Android SDK version to make your app compatible with the latest Android devices and features.

On the other hand, you should stop supporting old Android versions whenever possible.

I would recommend not targeting versions older than Android 10 (API level 29) unless you have a specific reason to do so at the time of writing.

Supporting older versions can lead to various issues, especially with newer libraries and features. You can update the target SDK version in the android/app/build.gradle file:

android {
    compileSdkVersion 36 // target the latest version (36 is Android 16)
    defaultConfig {
        applicationId "com.example.app"
        minSdkVersion 29 // minimum supported version (29 is Android 10)
        targetSdkVersion 36 // update this to the latest version
        versionCode 1
        versionName "1.0"
    }
    ...
}

NDK Issues

NDK (Native Development Kit) is used for building native libraries for Android. If you are using any native libraries in your Flutter project, you might encounter issues related to NDK.

You can see the current NDK version in the android/app/build.gradle file. Most of the time, it is set by the Flutter toolchain, but some packages require a specific NDK version.

This kind of error is usually comes with the message, which it says which NDK version is required.

android {
    ...
    ndkVersion "x.x.x" // use the recommended version
}

Updating JAVA_VERSION

Some packages are written in specific Java versions, and you need to set the Java version in your build.gradle file. Currently, Flutter will use Java 11 by default, but I have encountered issues with some packages that require Java 17.

android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17
    }
}

Missing SDK Components

A lot of times, the Gradle build fails because some SDK components are missing. This can happen if you have not installed the required components in the Android Studio SDK Manager.

Open up the Android Studio SDK Manager and check if you have the required components installed. The following components are usually required:

• Android SDK Build-Tools
• Android SDK Platform-Tools
• Android SDK Command-Line Tools
• NDK (side-by-side)
• Android Emulator
• Android SDK (for the target API level)

Incorrect Flutter Package Version

This is quite rare, but it happened to me 2-3 times in the past over the years.

During the update, Flutter caches the packages in its cache directory, and sometimes it can happen that the package is not updated correctly or is corrupted.

This results in the Gradle build failing with an error related to the package with no specific details about the issue.

To fix this, you can try to clear the Flutter cache and re-fetch the packages:

flutter pub cache repair

This will remove all the cached packages and re-fetch them from the pub.dev repository.

If you have slow internet connection, be prepared that this can take a while, as it will download all the packages again.

OutOfMemory Issues

Android Studio, Flutter and all the tooling can be quite memory hungry, especially when building large projects.

If you are running into OutOfMemory issues, you can try to increase the memory allocated to Gradle.

You can do this by adding the following line to your gradle.properties file:

org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError

This will increase the maximum heap size to 8GB and the maximum metaspace size to 4GB, which should be enough for most projects. In the past, the default was 4GB, which does not work for larger projects.

Feel free to adjust these values if you need more or less memory.

Multidex Issues

If your app has a lot of dependencies, you might run into the Multidex issues. This happens when the number of methods in your app exceeds the limit of 64K methods.

Packages drag a lot of dependencies, and it is easy to exceed this limit.

To fix this, you can enable Multidex in your build.gradle file:

android {
    ...
    defaultConfig {
        ...
        multiDexEnabled true
    }
} 

dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
}

Older Projects

Flutter has introduced many changes over the years, and older projects might not be compatible with the latest versions of Flutter, Gradle, or Android Gradle Plugin.

If you are on the latest Flutter version and your project does not work anymore, you should try to migrate it to the kts (Kotlin DSL) style, which is the new standard for Gradle build scripts.

I recommend going over the official Android documentation:

• Migrating to Kotlin DSL
• Migration from .apply to plugins
• Further breaking changes in Flutter

Windows Issues

At Windows, you might encounter additional issues during the build process.

Most of the time, the issue was related to Antivirus software or Windows Defender blocking the build process.

They can block Gradle from accessing the files it needs to build the project, which can lead to various errors.

If you are using Windows, I recommend adding the android directory to the exclusions in your Antivirus software or Windows Defender.

Be careful with this, as it can expose your system to security risks. Only do this if you trust the source of the project and you are sure that it is safe. Judge dependencies by their quality and reputation and avoid using shady or unmaintained packages.

Conclusion

Of course, there are many more issues happening and every one of them is unique.

If there was one tip I would give anyone who is starting with Flutter with no previous experience with any native development, it would be:

Make yourself familiar with underlying native platform and mainly with tooling it uses. Open up Android Studio/Xcode and try to run the project from there. It will give you more information about the issues and how to fix them. Moreover, it will be much more intuitive to debug the issues.

Other than that, always try to run flutter clean and flutter pub get before you start debugging any issues.

Hopefully, this article will help you to solve the most common Gradle issues in your Flutter projects.

If you have more tips or tricks that you use to solve Gradle issues in Flutter, feel free to share them.

Thanks for reading! If you have any questions or comments, feel free to reach out.

Subscribe for more