Fix the Gradle Issue: “The project is using an incompatible version of the Android Gradle plugin”

Seeing the “incompatible version of the Android Gradle plugin” error when opening or building your project in Android Studio? This error pops up when the Gradle plugin version doesn’t match what your Android Studio or Gradle wrapper expects. But don’t worry it’s fixable in just a few steps.

Step 1: Understand the Error

This issue usually means one of two things:

Your project is using an outdated plugin version that’s no longer supported by your version of Android Studio.
Or you’ve updated Android Studio, but the project’s Gradle plugin hasn’t caught up.

The key is to match the Gradle plugin version and the Gradle wrapper version to what Android Studio expects.

Step 2: Check the Error Message Details

First, look at the actual error message — it usually includes the current and required versions.

Example:

“The project is using an incompatible version of the Android Gradle plugin. The minimum supported version is X.Y.Z.”

Take note of what version is required — you’ll need it in the next step.

Step 3: Update the Android Gradle Plugin Version

Open your root-level build.gradle or build.gradle.kts file (not the one inside the app module)
Look for this section:

groovyCopyEditclasspath 'com.android.tools.build:gradle:OLD_VERSION'

Replace the version number with the one required by your Android Studio or the one in the error message.

Example:

groovyCopyEditclasspath 'com.android.tools.build:gradle:8.2.0'

Tip: You can find the latest compatible versions in the Android Gradle Plugin release notes.

Step 4: Update the Gradle Wrapper Version

Open gradle/wrapper/gradle-wrapper.properties
Find the distributionUrl and update the Gradle version to match the required one

Example:

propertiesCopyEditdistributionUrl=https\://services.gradle.org/distributions/gradle-8.4-all.zip

You can verify which Gradle versions are compatible with each plugin version here:
👉 Android Gradle Plugin Version Compatibility Table

Step 5: Sync the Project with Gradle Files

In Android Studio, click File → Sync Project with Gradle Files
Wait for the sync to complete

If everything matches up, the error should disappear. If not, double-check both version numbers.

Step 6: Invalidate Caches (Optional)

If you’re still seeing the error after updating:

Go to File → Invalidate Caches / Restart
Click Invalidate and Restart

This clears out any old data Android Studio might be holding onto.

Bonus Tip: Use the Upgrade Assistant

If you’re upgrading from a very old project, try using:

Tools → AGP Upgrade Assistant

It guides you through updating plugin versions safely and handles migration issues like namespace declarations or deprecated APIs.

You’re Good to Go

Once your Gradle plugin and wrapper versions are aligned, and the project syncs cleanly, you’re back in business. The app should build, run, and behave as expected in your current version of Android Studio.

Author
Recent Posts

Eric Sandler

Chief Writer at WiFi Planet

Eric Sandler is a veteran US tech writer with over 25 years of experience covering the latest advancements in the world of technology. From groundbreaking innovations to in-depth reviews, Eric has built a reputation for delivering insightful, reliable content. His work spans across a variety of tech topics, including smartphones, gadgets, AI, and more, making him a trusted voice in the industry.