How to Fix Android Gradle Plugin Version Mismatch Error

In this tutorial, you'll learn about How to Fix Android Gradle Plugin Version Mismatch Error. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

Your Android build fails with ERROR: Minimum supported Gradle version is X.X. Current version is Y.Y or The Android Gradle plugin requires Gradle X.X or higher. This happens when the Android Gradle Plugin (AGP) version declared in your project-level build.gradle is incompatible with the Gradle distribution version specified in gradle-wrapper.properties. AGP 8.2 requires Gradle 8.2+, AGP 8.1 requires 8.0+, and older combinations have their own constraints.

Quick Fix

1. Check current AGP and Gradle versions

First inspect both files simultaneously:

grep "com.android.tools.build:gradle" build.gradle
grep "distributionUrl" gradle/wrapper/gradle-wrapper.properties

Expected output:

classpath 'com.android.tools.build:gradle:8.2.0'
distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

2. Match AGP with the correct Gradle version

Use this compatibility table to identify the right pair:

Update gradle-wrapper.properties to use a compatible Gradle version:

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
networkTimeout=10000
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

3. Update the wrapper and sync

Download the new Gradle wrapper:

./gradlew wrapper --gradle-version=8.4

Expected output:

Downloading https://services.gradle.org/distributions/gradle-8.4-bin.zip
Unzipping...
Welcome to Gradle 8.4!

Then clean and rebuild:

./gradlew clean
./gradlew build

Expected output:

> Task :app:compileDebugKotlin
> Task :app:compileDebugJavaWithJavac
> Task :app:mergeDebugNativeLibs
BUILD SUCCESSFUL in 32s

4. Upgrade AGP if you want a newer version

In the project-level build.gradle:

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.2'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
    }
}

Then update Gradle to match the AGP requirement:

./gradlew wrapper --gradle-version=8.4

5. Verify the versions are in sync

./gradlew --version

Expected output:

Gradle 8.4
Android Gradle Plugin 8.2.2

6. Use the Gradle build scan to diagnose build issues

./gradlew build --scan

Expected output:

Publishing a build scan to scans.gradle.com requires accepting the Terms of Service.
Do you accept these terms? [yes, no] yes

The build scan URL shows every dependency version, task duration, and warning.

7. Use the Kotlin DSL version catalog for centralised version management

In gradle/libs.versions.toml:

[versions]
agp = "8.2.2"
gradle = "8.4"

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }

This keeps all version definitions in one file.

Prevention

• Pin both AGP and Gradle versions explicitly in your version control system
• Use the Gradle Versions Plugin (com.github.ben-manes.versions) to detect outdated dependencies
• Run ./gradlew wrapper --gradle-version=8.4 to update the wrapper safely without editing files manually
• Review the official AGP compatibility table before each upgrade
• Keep Kotlin and AGP versions aligned — check the Kotlin release notes for AGP compatibility before upgrading