Causes and Solutions for Android Studio “Minimum supported Gradle version is”

What Is “Minimum supported Gradle version is”?

“Minimum supported Gradle version is …” is an error displayed when the version of Gradle
currently being used is too old for the Android Gradle Plugin or other components being used.

For example, an error like the following may be displayed.

Minimum supported Gradle version is 8.7. Current version is 8.5.

In this case, at least Gradle 8.7 is required,
but the current project is using Gradle 8.5.

Basically, you need to change the Gradle version used by the project
to a version supported by the Android Gradle Plugin.

Main Causes

The main causes of “Minimum supported Gradle version is …” in Android Studio
include the following.

• The Gradle version is old
• Only the Android Gradle Plugin was updated to a newer version
• The Android Gradle Plugin was updated after updating Android Studio
• An old Android project was opened in a newer Android Studio
• An old Gradle version is specified in gradle-wrapper.properties
• The combination of Gradle and the Android Gradle Plugin is incompatible
• Multiple Gradle configurations are mixed together
• A different Gradle installation is being used instead of the Gradle Wrapper

Check the Versions in the Error Message

First, check the Gradle versions displayed in the error message.

Minimum supported Gradle version is 8.7. Current version is 8.5.

In this example,
the minimum required version is 8.7,
and the current version is 8.5.

Therefore, Gradle needs to be changed to a supported version of 8.7 or later.

Check gradle-wrapper.properties

If the Android project uses the Gradle Wrapper,
check the following file.

gradle/wrapper/gradle-wrapper.properties

The distributionUrl in this file
specifies the Gradle version to use.

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

In this example, Gradle 8.5 is used.

If the error states that Gradle 8.7 or later is required,
change it to a supported version.

Change the Gradle Version

If you are using the Gradle Wrapper,
change the distributionUrl in
gradle-wrapper.properties.

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.

Check the Android Gradle Plugin Version

The required Gradle version is related to the version of the Android Gradle Plugin being used.

Depending on the project,
the Android Gradle Plugin version may be configured as follows.

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

In older projects, it may also be configured in a format like the following.

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

Because the Android Gradle Plugin has corresponding Gradle versions,
updating only the Android Gradle Plugin may cause it to stop working with an older Gradle version.

Check the Combination of Gradle and the Android Gradle Plugin

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

Depending on the Android Gradle Plugin version,
requirements such as the minimum supported Gradle version are determined.

Therefore, when “Minimum supported Gradle version is …” is displayed,
check not only the Gradle version but also the Android Gradle Plugin version.

Check Whether Only the Android Gradle Plugin Was Updated

If only the Android Gradle Plugin is changed to a newer version,
the Gradle version may remain old.

For example, this can happen when the Android Gradle Plugin has been updated
while gradle-wrapper.properties still specifies an older Gradle version.

In this case,
check the versions of both the Android Gradle Plugin and Gradle,
and change them to a compatible combination.

When Opening an Old Project in a Newer Android Studio

Projects created with an older Android Studio
may use older versions of Gradle and the Android Gradle Plugin.

If you open such a project in a newer Android Studio
and update only some of the settings,
the combination of Gradle and the Android Gradle Plugin may become incompatible.

When updating an old project,
make changes while checking the compatibility among Gradle,
the Android Gradle Plugin,
JDK, and other components.

If It Occurred After Updating Android Studio

After updating Android Studio to a newer version,
you may be prompted to update the project’s Android Gradle Plugin.

As a result of updating the Android Gradle Plugin,
the Gradle version previously being used may no longer meet the minimum requirements,
causing “Minimum supported Gradle version is …” to occur.

In this case,
check the changes to the Android Gradle Plugin
and the Gradle Wrapper version.

Check Whether the Gradle Wrapper Is Being Used

Android projects normally use the Gradle Wrapper
to manage the Gradle version for each project.

Files such as the following exist in the project.

• gradlew
• gradlew.bat
• gradle/wrapper/gradle-wrapper.properties

When the Gradle Wrapper is used,
the Gradle version specified in
gradle-wrapper.properties
is used instead of the Gradle version installed system-wide.

Check the Current Gradle Version

You can check the current Gradle version from the Terminal
by using the Gradle Wrapper.

./gradlew --version

On Windows, depending on the environment, run the following.

gradlew.bat --version

Check whether the displayed Gradle version
meets the minimum version shown in the error.

Do Not Confuse the System Gradle with the Gradle Wrapper

If Gradle is installed separately on the PC,
simply running gradle in the Terminal
may use a different version from the project’s Gradle Wrapper.

gradle --version

and

./gradlew --version

may display different Gradle versions.

For Android projects,
check based on the project’s Gradle Wrapper configuration.

If Editing gradle-wrapper.properties Does Not Change Anything

Even after changing gradle-wrapper.properties,
the previous error may remain in Android Studio.

After making the change,
run Gradle Sync and check whether the new Gradle distribution is retrieved.

If necessary, restart Android Studio
and then run Gradle Sync again.

Run Gradle Sync Again

After changing the Gradle version,
run Gradle Sync again.

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

If a new Gradle version is required,
it may be downloaded during the first Sync.

Check the Internet Connection

When you change the Gradle Wrapper version,
the specified Gradle distribution may be retrieved from the internet.

If there is a problem with the internet connection,
the required Gradle version may not be retrieved
even if the Gradle version has been changed correctly.

If another download error is displayed after updating Gradle,
also check the network connection.

Check the JDK Version as Well

When Gradle is changed to a newer version,
another error may occur depending on the combination with the JDK being used.

If a JDK-related error is displayed after resolving the error concerning
the minimum Gradle version,
check the combination of the Android Gradle Plugin,
Gradle,
and JDK.

For example, an error like the following may be displayed.

Unsupported class file major version

Check the Gradle JDK

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

If another compatibility error occurs after updating Gradle,
check the Gradle JDK selected in Android Studio.

Check whether a JDK supported by the Android Gradle Plugin and Gradle
you are using is selected.

Do Not Update Gradle to a Newer Version Than Necessary

If “Minimum supported Gradle version is 8.7” is displayed,
you do not necessarily need to update Gradle to the latest version.

What is necessary is to change to a Gradle version
supported by the Android Gradle Plugin you are using.

If you change to a newer Gradle version than necessary,
compatibility problems with the Android Gradle Plugin
or other plugins may occur instead.

Check Multi-Module Projects

In a project containing multiple modules,
compatibility problems may occur due to the plugins being used
even if each module uses a common Gradle environment.

If a specific module or plugin name is displayed in the error,
also check the version of the plugin used by that module.

Check External Plugins

Gradle plugins other than the Android Gradle Plugin
may also require a specific Gradle version or later.

If the name of a plugin other than the Android Gradle Plugin
is displayed before or after the error message,
also check the Gradle versions supported by that plugin.

What to Check for Each Error

Depending on the Gradle version-related error,
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 “Minimum supported Gradle version is …” error message
2. Check the minimum required Gradle version
3. Check the Gradle version currently being used
4. Check gradle/wrapper/gradle-wrapper.properties
5. Check the Gradle version specified in distributionUrl
6. Check the Android Gradle Plugin version
7. Check the compatibility between Gradle and the Android Gradle Plugin
8. Change to a supported Gradle version
9. Run Gradle Sync again
10. Check the actual Gradle version with ./gradlew --version or a similar command
11. Check whether the system Gradle and Gradle Wrapper are being confused
12. Check the Gradle JDK if necessary
13. Also check the versions of external Gradle plugins
14. Restart Android Studio if necessary

Summary

Android Studio’s
“Minimum supported Gradle version is …”
is an error displayed when the Gradle version currently being used
does not meet the minimum version required by the Android Gradle Plugin or other components.

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

First, check the required Gradle version and the current Gradle version displayed in the error message,
and check the distributionUrl in
gradle/wrapper/gradle-wrapper.properties.

Then, while checking compatibility with the Android Gradle Plugin,
change to an appropriate Gradle version and run Gradle Sync again
to efficiently resolve the cause of the error.