Solutions for Android Studio “incompatible version of the Android Gradle plugin”

What Is “incompatible version of the Android Gradle plugin”?

“incompatible version of the Android Gradle plugin” is an error displayed
when the version of the Android Gradle Plugin being used
is incompatible with the current Android Studio, Gradle, or other components.

The error message may display
the version of the Android Gradle Plugin being used
and the range of supported versions.

In this case,
you need to check not only the Android Gradle Plugin,
but also the versions of Android Studio,
Gradle,
JDK, and other components.

Main Causes

The main causes of
“incompatible version of the Android Gradle plugin”
in Android Studio include the following.

• The Android Gradle Plugin version is old
• The Android Gradle Plugin version is too new
• The combination of Android Studio and the Android Gradle Plugin is incompatible
• The combination of Gradle and the Android Gradle Plugin is incompatible
• The JDK being used is not supported
• Only Android Studio was updated
• Only the Android Gradle Plugin was updated
• Only the Gradle Wrapper was updated
• An old Android project was opened in a newer Android Studio
• Different versions are specified in multiple plugins or configuration files

Check the Android Gradle Plugin Version

First,
check the version of the Android Gradle Plugin used by the project.

Depending on the project,
it may be configured as follows.

plugins {
    id("com.android.application") version "8.5.0" apply false
}

In older projects,
it may be configured as follows.

classpath 'com.android.tools.build:gradle:8.5.0'

Check whether the version specified here
is compatible with the current Android Studio and Gradle.

Check Compatibility with Android Studio

The Android Gradle Plugin cannot be used with every version of Android Studio.

If Android Studio is too old,
you may not be able to use a newer Android Gradle Plugin.

Conversely,
if a very old Android Gradle Plugin is used with a newer Android Studio,
you may be prompted to update it,
or compatibility warnings or errors may be displayed.

If the error occurred immediately after updating Android Studio,
check the version of the Android Gradle Plugin used by the project.

Check the Gradle Version

The Android Gradle Plugin has corresponding Gradle versions.

The Gradle version can normally be checked in the following file.

gradle/wrapper/gradle-wrapper.properties

Check the
distributionUrl
in the file.

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

If the combination of the Android Gradle Plugin and Gradle is incompatible,
change one of the versions to a compatible one.

Check the Combination of Gradle and the Android Gradle Plugin

The Android Gradle Plugin and Gradle
cannot be freely combined in any version combination.

Depending on the Android Gradle Plugin version,
the required minimum Gradle version and supported range differ.

If the error occurred after updating the Android Gradle Plugin,
check whether the Gradle Wrapper version has remained old.

If only Gradle was updated,
the Android Gradle Plugin may not support the newer Gradle version.

Update the Android Gradle Plugin

If the Android Gradle Plugin is too old,
update it to a supported version.

If you are using a plugins block,
change the version as follows, for example.

plugins {
    id("com.android.application") version "8.5.0" apply false
}

In an older project format,
change the classpath version as follows.

classpath 'com.android.tools.build:gradle:8.5.0'

When updating it,
also check the corresponding Gradle version.

Downgrade the Android Gradle Plugin

If the Android Gradle Plugin is too new,
returning it to an earlier version supported by Android Studio or Gradle
may resolve the problem.

Especially if the error occurred immediately after manually changing
only the Android Gradle Plugin to a newer version,
check the difference from the previous version.

In an environment where Android Studio cannot be updated,
another option is to downgrade the Android Gradle Plugin
to a compatible version.

Update the Gradle Wrapper

If Gradle is too old for the Android Gradle Plugin,
update the Gradle Wrapper.

Check the
distributionUrl
in
gradle/wrapper/gradle-wrapper.properties
and change it to a supported Gradle version.

For example, to change to Gradle 8.7,
configure it as follows.

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

After making the change,
run Gradle Sync again.

Do Not Make Gradle Newer Than Necessary

If you update Gradle to the latest version,
the Android Gradle Plugin you are using may not support it.

If Gradle is too new for the Android Gradle Plugin,
you need to return it to a supported Gradle version.

Therefore,
when changing Gradle,
first check its compatibility with the Android Gradle Plugin.

Check the JDK Version

When you change the version of the Android Gradle Plugin or Gradle,
the requirements for the JDK being used may also change.

If a JDK-related error occurs after correcting
the combination of the Android Gradle Plugin and Gradle,
check the version of the JDK being used.

In Android Studio,
you can configure the JDK used by Gradle.

Check the Gradle JDK

If the Gradle JDK selected in Android Studio
is not compatible with the Android Gradle Plugin or Gradle being used,
the build or Gradle Sync may fail.

Check the JDK used by Gradle
in the Android Studio settings.

Using the JDK bundled with Android Studio
may also reduce differences between environments.

If Only Android Studio Was Updated

Even if only Android Studio is updated
and the project’s Gradle or Android Gradle Plugin has not been changed,
you may be prompted to update an old project.

In this case,
check the guidance or error message displayed after updating Android Studio,
and change the Android Gradle Plugin and Gradle
to a compatible combination.

If Only the Android Gradle Plugin Was Updated

If only the Android Gradle Plugin was updated,
the Gradle Wrapper or JDK may still be old.

In particular,
an error like the following may subsequently be displayed.

Minimum supported Gradle version is ...

In this case,
check the Gradle version required by the Android Gradle Plugin
and change the Gradle Wrapper accordingly.

If Only the Gradle Wrapper Was Updated

If only the Gradle Wrapper is updated,
the Android Gradle Plugin may not support that Gradle version.

If a compatibility error occurs immediately after updating Gradle,
also check the Android Gradle Plugin version.

When Opening an Old Project in a Newer Android Studio

In an old Android project,
the Android Gradle Plugin,
Gradle,
JDK, and other components may use an old configuration.

If such a project is opened in a newer Android Studio,
multiple compatibility errors may occur one after another.

Rather than changing everything to the latest version at once,
update the Android Gradle Plugin,
Gradle,
and JDK in order
while checking their compatibility.

Check the Version Catalog

In newer Android project formats,
plugin versions may be managed using a Version Catalog.

For example,
check a file such as the following.

gradle/libs.versions.toml

If the Android Gradle Plugin version is written in this file,
changing only
build.gradle
or
build.gradle.kts
may not change the version.

Check Multiple Configuration Locations

Depending on the project,
the Android Gradle Plugin version may be managed in multiple locations.

For example,
check locations such as the following.

• build.gradle
• build.gradle.kts
• settings.gradle
• settings.gradle.kts
• gradle/libs.versions.toml

Even if you think you changed the version,
it may actually be loaded from another configuration file.

Run Gradle Sync Again

After changing the Android Gradle Plugin or Gradle version,
run Gradle Sync again.

Run
Sync Project with Gradle Files
or a similar option from Android Studio.

If the required Gradle or plugins have not yet been obtained,
they may be downloaded during Sync.

Check the Internet Connection

When you change the version of the Android Gradle Plugin or Gradle,
the required files may be obtained from the internet.

If there is a problem with the network connection,
even if you change to compatible versions,
the plugin or Gradle may not be obtained,
resulting in another error.

If a download-related error is displayed after the update,
also check the internet connection.

Run Clean Project

If old build information remains after changing versions,
running Clean Project may improve the situation.

Run
Clean Project
from the Build menu or another location in Android Studio,
and then run Gradle Sync or Rebuild Project.

Restart Android Studio

If the error display does not change
even after changing the Gradle or Android Gradle Plugin settings,
restart Android Studio and run Gradle Sync again.

If the previous state remains on the IDE side,
restarting may cause the changes to be reflected.

What to Check for Each Error

Depending on the error related to the Android Gradle Plugin or Gradle,
you can narrow down what should be checked to some extent.

Steps to Check If the Problem Is Not Resolved

If you do not know the cause,
checking the following in order makes it easier to narrow down the problem.

1. Check the full “incompatible version of the Android Gradle plugin” error message
2. Check the version of the Android Gradle Plugin being used
3. Check compatibility with the Android Studio version
4. Check the Gradle version in gradle-wrapper.properties
5. Check the compatibility between the Android Gradle Plugin and Gradle
6. Update or change the Android Gradle Plugin if necessary
7. Change the Gradle Wrapper to a compatible version if necessary
8. Check the JDK version
9. Check the Gradle JDK settings
10. If a Version Catalog is being used, check libs.versions.toml
11. Check whether different versions are specified in multiple configuration files
12. Run Gradle Sync again
13. Run Clean Project if necessary
14. Restart Android Studio if necessary

Summary

Android Studio’s
“incompatible version of the Android Gradle plugin”
is an error displayed when the versions of the Android Gradle Plugin,
Android Studio,
Gradle,
JDK, and other components are incompatible.

It may occur especially when Android Studio or the Android Gradle Plugin is updated,
or when an old Android project is opened in a newer environment.

First, check the Android Gradle Plugin version,
and then check the Gradle version in
gradle/wrapper/gradle-wrapper.properties.

Then,
check the compatibility among Android Studio,
the Android Gradle Plugin,
Gradle,
and JDK,
change them to a compatible combination,
and run Gradle Sync again
to efficiently narrow down the cause.