Could not find or load main class org.gradle.wrapper.GradleWrapperMain

Troubleshooting 'Could not find or load main class org.gradle.wrapper.GradleWrapperMain'

This article provides comprehensive solutions and debugging strategies for the common Gradle error 'Could not find or load main class org.gradle.wrapper.GradleWrapperMain' encountered in Android Studio and other Gradle-based projects.

The error message Could not find or load main class org.gradle.wrapper.GradleWrapperMain is a common hurdle for developers working with Gradle, especially in Android Studio projects. This typically indicates an issue with how Gradle is set up or how its wrapper script (gradlew or gradlew.bat) is trying to execute the Gradle build. This article will walk you through the common causes and provide step-by-step solutions to resolve this problem, ensuring your projects build successfully.

Understanding the Gradle Wrapper

Before diving into solutions, it's crucial to understand what the Gradle Wrapper is. The Gradle Wrapper is a script that invokes a declared version of Gradle, downloading it beforehand if necessary. This ensures that everyone building the project uses the exact same Gradle version, leading to consistent and reliable builds across different development environments. The org.gradle.wrapper.GradleWrapperMain class is the entry point for this wrapper mechanism.

flowchart TD
    A[Developer runs ./gradlew build] --> B{Is Gradle distribution present?}
    B -- No --> C[Download Gradle distribution]
    C --> D[Extract Gradle distribution]
    B -- Yes --> D
    D --> E[Execute org.gradle.wrapper.GradleWrapperMain]
    E --> F[Gradle Build Process Starts]
    F --> G[Build Successful]

Simplified flow of the Gradle Wrapper execution

Common Causes and Solutions

This error usually stems from a corrupted or incomplete Gradle distribution, incorrect file permissions, or environmental issues. Let's explore the most frequent causes and their corresponding fixes.

1. Solution 1: Clean and Re-download Gradle Wrapper

The most common fix is to remove the existing Gradle wrapper files and let Gradle re-download them. This ensures you have a fresh, uncorrupted distribution.

2. Step 1.1: Delete the .gradle directory

Navigate to your project's root directory and delete the .gradle folder. This folder contains cached Gradle distributions and other build artifacts. On Linux/macOS, use rm -rf .gradle. On Windows, you can delete it via File Explorer.

3. Step 1.2: Delete the gradle/wrapper directory

Inside your project's root, delete the gradle/wrapper directory. This directory contains the gradle-wrapper.jar and gradle-wrapper.properties files, which are crucial for the wrapper's operation. On Linux/macOS, use rm -rf gradle/wrapper. On Windows, delete it via File Explorer.

4. Step 1.3: Re-import or Sync Project

After deleting these directories, open your project in Android Studio. It should prompt you to sync the project with Gradle files, which will trigger a re-download of the Gradle wrapper. If not, manually sync by going to File > Sync Project with Gradle Files.

1. Solution 2: Check gradle-wrapper.properties

The gradle-wrapper.properties file defines which Gradle version the wrapper should use and where to download it from. Incorrect configuration here can lead to issues.

2. Step 2.1: Locate the file

Open gradle/wrapper/gradle-wrapper.properties in your project's root directory.

3. Step 2.2: Verify distributionUrl

Ensure the distributionUrl points to a valid Gradle distribution. It should look something like this:

4. Step 2.3: Example gradle-wrapper.properties

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

Make sure there are no typos, extra spaces, or incorrect URLs. The version number (e.g., 7.4.2) should match the desired Gradle version for your project.

1. Solution 3: Verify gradlew Permissions (Linux/macOS)

On Unix-like systems, the gradlew script needs execute permissions to run. If it lacks these, you'll encounter errors.

2. Step 3.1: Navigate to project root

Open your terminal and change directory to your project's root.

3. Step 3.2: Grant execute permissions

Run the command: chmod +x gradlew

4. Step 3.3: Try building again

Attempt to run your Gradle command (e.g., ./gradlew build) after granting permissions.

1. Solution 4: Check Java Environment

Gradle requires a Java Development Kit (JDK) to run. Ensure your JAVA_HOME environment variable is correctly set and points to a valid JDK installation.

2. Step 4.1: Verify JAVA_HOME

Open your terminal/command prompt and type echo $JAVA_HOME (Linux/macOS) or echo %JAVA_HOME% (Windows). Ensure the path is correct and the JDK version is compatible with your Gradle version.

3. Step 4.2: Update JAVA_HOME if necessary

If JAVA_HOME is incorrect or missing, set it to the path of your JDK installation. For example, on Linux/macOS: export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home.

4. Step 4.3: Configure JDK in Android Studio

In Android Studio, go to File > Project Structure > SDK Location and ensure the 'JDK location' is correctly set to your desired JDK.

Advanced Troubleshooting

If the above solutions don't work, consider these more advanced steps.

1. Solution 5: Invalidate Caches / Restart Android Studio

Sometimes, Android Studio's internal caches can become corrupted. Invalidating them can resolve various build issues.

2. Step 5.1: Invalidate Caches

In Android Studio, go to File > Invalidate Caches / Restart....

3. Step 5.2: Select 'Invalidate and Restart'

Choose the 'Invalidate and Restart' option. This will clear caches and restart the IDE, often resolving stubborn problems.

1. Solution 6: Check for Antivirus/Firewall Interference

Occasionally, antivirus software or firewalls can block Gradle from downloading necessary files or executing its wrapper. Temporarily disabling them (with caution) or adding exceptions might help.

2. Step 6.1: Temporarily disable security software

If possible, temporarily disable your antivirus or firewall and try to build the project. If it works, you'll need to configure an exception for Gradle.

3. Step 6.2: Add exceptions

Add exceptions for your project directory and the Gradle user home directory (usually ~/.gradle or %USERPROFILE%/.gradle) to your security software.

1. Solution 7: Reinstall Gradle (System-wide)

If you have a system-wide Gradle installation that's causing conflicts, consider reinstalling it or ensuring your project explicitly uses the wrapper.

2. Step 7.1: Uninstall existing Gradle

Follow the uninstallation instructions for your operating system (e.g., brew uninstall gradle on macOS, remove from PATH on Windows).

3. Step 7.2: Reinstall Gradle (optional)

If you still need a system-wide Gradle, reinstall it using your preferred package manager or by downloading from the official Gradle website.