Causes and Solutions for Android Studio “Gradle sync failed”

What Is “Gradle sync failed”?

“Gradle sync failed” indicates that Android Studio attempted to load the Gradle project settings
and synchronize the project structure, dependencies, and other information,
but the synchronization process could not be completed because of an error.

During Gradle Sync, information such as the following is mainly checked.

• Gradle version
• Android Gradle Plugin version
• JDK to use
• Project and module settings
• Dependencies
• Repository settings
• SDK and build settings

If there is a problem with any of these, Gradle Sync may fail.

Main Causes

The main causes of “Gradle sync failed” in Android Studio include the following.

• The Gradle version is incompatible
• The Android Gradle Plugin version is incompatible
• There is a problem with the combination of Gradle and Android Gradle Plugin
• The JDK version is incompatible
• Dependency retrieval has failed
• A nonexistent library or version has been specified
• There is a problem with the repository settings
• There is a problem with the internet connection
• Gradle Offline mode is enabled
• There is a problem with the proxy or VPN
• There is an error in a Gradle configuration file
• There is a problem with the Gradle cache
• There is a problem with the Android SDK settings

Check the Detailed Error Message

First, check the entire error displayed in the Android Studio Build window or Gradle Sync results.

Another error indicating the cause may be displayed before or after “Gradle sync failed.”

Gradle sync failed

Could not resolve all files for configuration ':app:debugRuntimeClasspath'.

In this case, you can determine that the cause is not Gradle Sync itself,
but a failure to retrieve or resolve dependencies.

Errors like the following may also be displayed.

Unsupported class file major version

Minimum supported Gradle version is ...

Could not find ...

Could not GET ...

What you should check depends on the detailed error that is displayed.

Check the Gradle Version

If the Gradle version used by the project is not compatible with the Android Gradle Plugin or other components,
synchronization may fail.

If you are using the Gradle Wrapper,
check
gradle/wrapper/gradle-wrapper.properties.

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

Check the Gradle version specified in this
distributionUrl.

Check the Android Gradle Plugin Version

Gradle Sync may also fail if the Android Gradle Plugin version is not compatible with the Gradle version being used.

Depending on the project, the plugin version may be configured as follows.

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

Gradle and Android Gradle Plugin have compatibility relationships,
so updating only one of them may prevent synchronization.

Check whether the Gradle version is compatible with the Android Gradle Plugin you are using.

Check the JDK Version

Because Gradle runs on Java, synchronization may also fail if the JDK version being used is incompatible.

In Android Studio, you can configure the JDK that Gradle uses.

Check whether the JDK version required by the project or Android Gradle Plugin
matches the Gradle JDK selected in Android Studio.

If there is a JDK mismatch, an error like the following may be displayed.

Unsupported class file major version

Check for Dependency Retrieval Errors

During Gradle Sync, Gradle retrieves the dependencies for libraries and plugins used by the project.

If that retrieval fails, the entire Gradle Sync process may fail.

For example, errors like the following may be displayed.

Could not resolve all files for configuration

Could not resolve ...

Could not find ...

Could not GET ...

In this case, check the dependencies, library versions, repository settings,
network, and related items.

Check the Library Name and Version

If a nonexistent library name or version is specified,
Gradle cannot retrieve the dependency and synchronization will fail.

implementation("com.example:library:9.9.9")

Check the official documentation for the library you are using
to confirm that the library name and version are correct.

Check the repositories Settings

If the repository where a library or plugin is published is not configured,
Gradle cannot retrieve the required dependencies.

In Android projects, repositories such as the following are commonly used.

repositories {
    google()
    mavenCentral()
}

In current Gradle projects,
the repositories may be configured inside
dependencyResolutionManagement
in
settings.gradle
or
settings.gradle.kts.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
    }
}

Depending on the library being used, an additional Maven Repository may be required.

Check the Repositories for Plugins

If retrieval of a Gradle plugin is failing,
check the repository settings for plugins separately from normal dependencies.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Also check whether the plugin ID and version are correct.

Check the Internet Connection

During Gradle Sync, required dependencies may be retrieved from repositories on the internet.

If there is no internet connection or the connection is unstable,
Gradle Sync may fail.

Check the internet connection using a browser or another method,
and reconnect if Wi-Fi or another connection is unstable.

Check Gradle Offline Mode

When Gradle Offline mode is enabled,
dependencies are basically resolved using only the cache stored locally.

If the required libraries or plugins have not yet been downloaded,
they cannot be retrieved in Offline mode, and Gradle Sync may fail.

Check the Gradle settings in Android Studio,
and if Offline mode is enabled, disable it and then run Gradle Sync again.

Check the Proxy Settings

On company or school networks,
a proxy may be required to connect to the external internet.

If the proxy settings in Android Studio or Gradle are incorrect,
Gradle may be unable to access repositories and synchronization may fail.

Check the proxy settings in Android Studio and the proxy information configured in
gradle.properties.

Check the VPN and Firewall

External communication from Gradle or Java may be restricted by a VPN, firewall, security software, or similar system.

Even if the browser can connect to the internet,
Gradle alone may be unable to connect to external repositories.

If synchronization works normally on another network,
the current network environment or security settings may be the cause.

Check the Contents of build.gradle and settings.gradle

If there is a syntax error or writing mistake in a Gradle configuration file,
Gradle Sync will not complete successfully.

Mainly check the following files.

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

If a line number is displayed in the error,
check the code around that location.

Check the Difference Between Groovy DSL and Kotlin DSL

The way settings are written in Gradle configuration files may differ between Groovy DSL and Kotlin DSL.

In Kotlin DSL, for example, dependencies are written as follows.

dependencies {
    implementation("com.example:library:1.0.0")
}

In Groovy DSL, they may be written as follows.

dependencies {
    implementation 'com.example:library:1.0.0'
}

If you copied sample code from the web,
check whether it matches the DSL used by your project.

Check Version Catalog

If you are using Gradle Version Catalog,
synchronization may fail if there is an error in the
libs.versions.toml
settings.

[versions]
example = "1.0.0"

[libraries]
example-library = { module = "com.example:library", version.ref = "example" }

Check whether there are any errors in the library name, module, version,
version.ref,
or other settings.

Check the Android SDK Settings

Gradle Sync or the build may also fail if the Android SDK required by the project is not installed
or if there is a problem with the SDK settings.

Check the SDK Manager in Android Studio
and confirm that the SDK Platform, Build Tools, and other components required by the project are installed.

Check Settings Such as compileSdk

An error may occur if the SDK specified by
compileSdk
or another setting in the project is not installed.

android {
    compileSdk = 35
}

Check whether the specified SDK version is installed in Android Studio.

Run Gradle Sync Again

If the problem is a temporary communication error or a processing failure on the Gradle side,
running Gradle Sync again may resolve it.

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

If you modified a configuration file,
run Gradle Sync again after making the correction.

Retrieve Dependencies Again

If there is a problem with the Gradle cache or the dependency retrieval state,
retrieving the dependencies again may improve the situation.

Run the following from the project’s Terminal.

./gradlew build --refresh-dependencies

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

gradlew.bat build --refresh-dependencies

This retries dependency retrieval.

Run Clean Project

If there is a problem with files generated during the build process,
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 as necessary.

Check the Gradle Cache

If the Gradle cache is corrupted or inconsistent,
dependencies may not be loaded correctly and synchronization may fail.

First, try retrieving the dependencies again with
--refresh-dependencies
or a similar method.

If you manually delete the cache,
do so with the understanding that the required files will need to be downloaded again.

Restart Android Studio

If synchronization does not proceed correctly because of a temporary state in Android Studio,
restarting Android Studio may improve the situation.

If the situation does not change even after modifying settings,
close Android Studio once, reopen the project, and run Gradle Sync again.

When Opening an Old Project

If you open a project created with an old version of Android Studio in a newer version of Android Studio,
Gradle, Android Gradle Plugin, JDK, repositories, dependencies, and other settings may no longer match the current environment,
causing Gradle Sync to fail.

Especially for projects that have not been updated for a long time,
do not change only Gradle to the latest version all at once.
Update it while checking compatibility with Android Gradle Plugin and JDK.

What to Check for Each Error

The error displayed together with “Gradle sync failed”
can help narrow down what should be checked.

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 detailed error displayed together with “Gradle sync failed”
2. Check whether the error is related to dependencies, Gradle, JDK, or SDK
3. Check the Gradle version
4. Check the Android Gradle Plugin version
5. Check the Gradle JDK
6. Check the library name and version
7. Check the repositories settings
8. Check the pluginManagement settings
9. Check the internet connection and Offline mode
10. Check the proxy, VPN, and firewall
11. Check the contents of build.gradle, settings.gradle, and related files
12. If you are using Version Catalog, check libs.versions.toml
13. Check the Android SDK and settings such as compileSdk
14. Run Gradle Sync again
15. Retrieve dependencies again with --refresh-dependencies
16. Try Clean Project or restarting Android Studio as necessary

Summary

Android Studio’s
“Gradle sync failed”
is an error displayed when synchronization of the Gradle project settings does not complete successfully.

It may occur for various reasons,
including the Gradle or Android Gradle Plugin version,
JDK, dependencies, repositories, network, Gradle configuration files,
and Android SDK.

First, do not judge the problem based only on the “Gradle sync failed” message.
Check the detailed error message displayed in the Build window or elsewhere.
Then check the combination of Gradle, Android Gradle Plugin, and JDK,
followed by dependencies, repositories, network, and configuration files,
to efficiently narrow down the cause.