Resolving "Your project requires a newer version of the Kotlin Gradle plugin" error

Problem

When updating Flutter projects or migrating to null safety, you may encounter an error stating that your project requires a newer version of the Kotlin Gradle plugin. The error message typically appears as:

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

This issue occurs when your project's Kotlin version is incompatible with the requirements of your Flutter project or its dependencies.

Primary Solution: Update Kotlin version

The most effective solution is to update the Kotlin version in your project's configuration files.

For Flutter projects created before version 3.19

1. Update android/build.gradle:

   Navigate to project_name/android/build.gradle and update the Kotlin version:

   buildscript {
       ext.kotlin_version = '2.1.10' // Use latest version
       repositories {
           google()
           mavenCentral()
       }
   
       dependencies {
           classpath 'com.android.tools.build:gradle:7.3.0'
           classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
       }
   }

2. Update dependencies in android/app/build.gradle:

   Ensure your dependencies use the same Kotlin version:

   dependencies {
       implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
       // Other dependencies...
   }

For newer Flutter projects (version 3.19+)

1. Update android/settings.gradle:

   Modern Flutter projects manage Kotlin version in the settings file:

   pluginManagement {
       // Other settings...
       
       plugins {
           id "dev.flutter.flutter-plugin-loader" version "1.0.0"
           id "com.android.application" version "8.1.0" apply false
           id "org.jetbrains.kotlin.android" version "2.1.10" apply false // Update this line
       }
   }

TIP

Always check for the latest Kotlin version on the official Kotlin releases page before updating.

Alternative: Creating a new project reference

If you're unsure about the correct configuration, create a new Flutter project and compare its Android configuration files with your existing project:

flutter create temp_project

Compare the following files between your project and the new one:

• android/settings.gradle
• android/build.gradle
• android/app/build.gradle
• android/gradle/wrapper/gradle-wrapper.properties

Additional troubleshooting steps

If updating the Kotlin version doesn't resolve the issue, try these steps:

1. Clean your project:

   flutter clean

2. Update Gradle wrapper:

   In android/gradle/wrapper/gradle-wrapper.properties, ensure you're using a compatible Gradle version:

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

3. Invalidate caches and restart:

   In Android Studio, go to File > Invalidate Caches / Restart.

4. Check for process conflicts:

   On Windows, sometimes the OpenJDK Platform binary process might prevent file operations. Check Task Manager and terminate any conflicting Java processes.

WARNING

Avoid deleting the android folder and recreating it with flutter create . unless absolutely necessary, as this might overwrite your custom configurations.

Verifying the fix

After making changes, verify the fix by running:

flutter run

Or build your APK:

flutter build apk

Common pitfalls

1. Mismatched versions: Ensure all Kotlin references point to the same version across all configuration files.

2. Outdated Gradle plugin: Update the Android Gradle plugin version in android/build.gradle to match your Kotlin version requirements.

3. Dependency conflicts: Some Flutter packages may require specific Kotlin versions. Check your dependencies if issues persist.

By following these steps, you should resolve the Kotlin Gradle plugin version error and successfully build your Flutter application.