Resolving 'Android Gradle Plugin Requires Java 11 to Run' Error with Java 1.8

Error Background and Problem Analysis

In the Android development environment, Gradle serves as the primary build tool, and the compatibility between its version and the Java runtime environment is crucial. When developers upgrade to newer versions of Android Studio or use the latest Android Gradle plugins, they frequently encounter Java version mismatch errors. Specifically, the build process may display the error message "Android Gradle plugin requires Java 11 to run. You are currently using Java 1.8".

The root cause of this error lies in the fact that Android Gradle plugin version 7.0.0 and above mandates the use of Java 11 as the runtime environment, while the system might still be configured with the older Java 8 version. Even if developers have installed Java 11 on their systems, if the Gradle build process fails to correctly recognize and use this version, the error will persist.

Java Version Management Mechanism in Gradle Build System

The Gradle build system manages Java version usage through multiple layers of configuration. First, the system environment variable JAVA_HOME defines the default Java installation path. Second, the Gradle Wrapper can specify a particular Java version through the org.gradle.java.home property in the gradle.properties file. Finally, Android Studio's IDE settings can separately configure the JDK for the Gradle build process.

When conflicts or inconsistencies exist among these configurations, Gradle may fail to correctly use the required Java version. For instance, even if the correct JAVA_HOME environment variable is set in the system, if Android Studio's Gradle settings still point to Java 8, the build process will still fail.

Solution: Multi-level Configuration Verification

To thoroughly resolve this issue, configuration verification and adjustments need to be performed at multiple levels. Below are the detailed resolution steps:

Verify Current Java Version Used by Gradle

First, verify the actual Java version used by Gradle through the command line. Execute the following command in the project root directory:

./gradlew --version

This command outputs detailed version information about Gradle, including the JVM version being used. If the output shows JVM version 1.8, it confirms that Gradle is indeed using Java 8, requiring further configuration.

Below is an example of the expected correct output:

Gradle 7.0-rc-2
------------------------------------------------------------

Build time:   2021-04-01 21:26:39 UTC
Revision:     912a3368b654b71250dfc925a20d620393

Kotlin:       1.4.31
Groovy:       3.0.7
Ant:          Apache Ant(TM) version 1.10.9 compiled on September 27 2020
JVM:          11.0.10 (Ubuntu 11.0.10+9-Ubuntu-0ubuntu1.20.10)
OS:           Linux 5.11.4-051104-generic amd64

Configure Gradle JDK Settings in Android Studio

If command-line verification shows that Gradle is using the wrong version, configuration adjustments are needed in Android Studio:

1. Open Android Studio and navigate to "Preferences" (Mac) or "Settings" (Windows/Linux)
2. Go to "Build, Execution, Deployment" → "Build Tools" → "Gradle"
3. In the "Gradle JDK" setting, select the installed Java 11 version
4. Click "Apply" and "OK" to save the settings

This setting ensures that the Gradle build process within Android Studio uses the specified Java 11 environment.

Environment Variable Configuration Verification

In addition to IDE settings, system environment variable configuration needs verification. Execute the following command in the terminal to check the JAVA_HOME environment variable:

echo $JAVA_HOME

On Windows systems, use:

echo %JAVA_HOME%

Ensure the output path points to the Java 11 installation directory. If the path is incorrect, update the environment variable.

Gradle Properties File Configuration

In the project's gradle.properties file, explicitly specify the Java version used by Gradle:

org.gradle.java.home=/path/to/your/jdk-11

This configuration overrides the system's default Java version settings, ensuring the Gradle build process uses the specified Java 11 environment.

Build Configuration File Compatibility Settings

Beyond runtime environment configuration, ensure that Java version settings in project build files are correct. The module-level build.gradle file should include the following configurations:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    
    kotlinOptions {
        jvmTarget = "11"
    }
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(11))
    }
}

These configurations ensure that both the compilation process and Kotlin compilation use Java 11 as the target version.

Version Compatibility Considerations

While resolving Java version issues, attention must also be paid to compatibility between Gradle versions and Android Gradle plugins. Android Gradle plugin 7.0.0 requires Gradle 7.0 or above. Check the distributionUrl in the gradle-wrapper.properties file:

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

If using an older Gradle version, update to a compatible version.

Verifying Solution Effectiveness

After completing all configurations, restart Android Studio and perform a complete project clean and rebuild:

1. Execute "File" → "Invalidate Caches / Restart"
2. Clean the project: ./gradlew clean
3. Rebuild the project: ./gradlew build

If the build completes successfully, the Java version configuration issue has been resolved.

Common Issues and Troubleshooting

Several common issues may arise during the configuration process:

• Multiple Java Versions Coexisting: When multiple Java versions are installed on the system, ensure all relevant configurations point to the correct Java 11 version
• Permission Issues: On some systems, administrator privileges may be required to modify environment variables or installation directory permissions
• Cache Issues: Gradle and Android Studio caches might prevent configuration changes from taking effect immediately, requiring cache clearance
• Project-Specific Configurations: Some projects may have special Gradle configurations that override global settings, necessitating checks of project-specific gradle.properties files

Through systematic configuration verification and step-by-step problem troubleshooting, the mismatch between Android Gradle plugins and Java versions can be effectively resolved, ensuring development environment stability and compatibility.