Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Android Gradle plugin requires Java 17 to run: where the JDK comes from

Gradle picks its JVM from several places. Make gradle.properties, JAVA_HOME, Studio and CI agree, and stop the stale daemon afterwards.

~6 min readJava
#Android#Gradle#Java#CI
An android gradle build cube demanding a jdk crate, an amber java 11 crate rejected and a cyan jdk 17 crate

Introduction & Quick Summary

Android Gradle plugin requires Java 17 to run. You are currently using Java 11 arrives when Gradle applies the Android plugin with a JDK older than the plugin's minimum. Nothing in the project is wrong: the build is running on the wrong JVM, and Gradle tells you so before compiling a single source file.

There are only three places the JDK can come from, and the fix is to make all of them agree:

  • JAVA_HOME. The process environment wins for command-line builds and CI.
  • org.gradle.java.home in gradle.properties. Gradle-specific and easy to forget; it overrides JAVA_HOME.
  • Android Studio's Gradle JDK setting. Studio starts its own daemon with the JDK selected in Preferences, so a correct JAVA_HOME in the terminal does not help the IDE.
SymptomWhich JDK is in useWhere to change it
Fails in terminal, works in StudioShell JAVA_HOMEExport JAVA_HOME for the shell
Works in terminal, fails in StudioStudio Gradle JDKSettings → Build Tools → Gradle
Fails only in CIRunner JDKactions/setup-java or the Docker image
Fails after adding org.gradle.java.homeThat propertyCorrect or remove the path
Says Java 11 but java -version is 17Daemon reuse./gradlew --stop

Core Mechanics, Signatures & Reproducible Setup

Gradle runs a daemon in a JVM, and the Android plugin checks that JVM's version when it is applied. The check is not about compileOptions or jvmTarget; those affect the bytecode the compiler produces. The daemon JDK is about the toolchain that runs the build, and AGP 8.x requires 17 or newer for it.

The JVM is chosen in a fixed order: org.gradle.java.home from the project or user gradle.properties, then the JAVA_HOME environment variable, then java on the PATH, then the JDK bundled with Android Studio when the IDE launched the build. A stale daemon keeps the JVM it started with, so changing configuration without stopping the daemon can appear to do nothing.

Reproduce it by pointing JAVA_HOME at Java 11 while the project uses AGP 8:

bash
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 ./gradlew :app:assembleDebug
text
FAILURE: Build failed with an exception. * Where: Build file '/home/me/app/build.gradle.kts' line: 1 * What went wrong: An exception occurred applying plugin request [id: 'com.android.application'] > Failed to apply plugin 'com.android.internal.application'. > Android Gradle plugin requires Java 17 to run. You are currently using Java 11. You can try some of the following options: - changing the JAVA_HOME environment variable - changing the JDK path under the 'Gradle JDK' setting in Android Studio - using the '-Dorg.gradle.java.home' command-line option

Key Comparison Table

The plugin version sets the floor, so the first check is whether the project and the JDK are compatible at all.

AGP versionMinimum GradleMinimum JDK to runcompileSdk supported
8.0–8.28.01734
8.3–8.58.41734
8.6–8.78.71735
8.8–8.108.91735
7.47.51133

The setting location explains most "it works for them but not for me" reports, because each entry overrides the one below it.

Where the JDK is chosenScopeOverrides
org.gradle.java.home in gradle.propertiesProject or userJAVA_HOME, PATH
JAVA_HOMEShell, CI jobPATH
PATH lookupShell, CI jobStudio JDK
Android Studio Gradle JDKIDE-launched buildsNothing outside the IDE

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Point JAVA_HOME at 17 and stop the old daemon

The environment change is the quickest fix, and stopping the daemon is what makes it take effect in a shell that already ran a build:

bash
export JAVA_HOME=$(/usr/libexec/java_home -v 17) # macOS # export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 # Linux java -version ./gradlew --stop ./gradlew :app:assembleDebug

./gradlew --stop terminates daemons started by that Gradle version for the current user. Without it, Gradle may hand the build to a daemon already running on 11, and the error survives the export.

Pin the JDK for everyone with gradle.properties

A project-level property removes the dependence on each developer's shell:

properties
# gradle.properties org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8 org.gradle.java.home=/usr/lib/jvm/java-17-openjdk-amd64

The path is absolute and machine-specific, so committing it breaks every teammate whose JDK lives elsewhere. Two workable options: keep it in ~/.gradle/gradle.properties (user scope, not committed), or use a toolchain block so Gradle can download a matching JDK:

kotlin
// build.gradle.kts kotlin { jvmToolchain(17) }

jvmToolchain(17) affects compilation and Kotlin targets. It does not change the daemon JVM that applies the Android plugin, so it cannot fix this particular error on its own; it is what keeps jvmTarget consistent once the build runs at all.

Android Studio's Gradle JDK

Studio ignores your shell environment for Gradle. Set the IDE's own JDK in Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK, choosing the bundled JetBrains Runtime 17 or a local JDK 17. The same screen shows the value Studio currently uses, which is the fastest way to confirm a mismatch when the terminal builds and the IDE does not.

Command-line equivalent for a single invocation:

bash
./gradlew -Dorg.gradle.java.home=/usr/lib/jvm/java-17-openjdk-amd64 :app:assembleDebug

That flag is useful for proving the theory before changing any config: if the build succeeds with it, the JDK selection is the whole problem.

CI runners

A workflow that installs Java 11 for an unrelated Gradle plugin will fail at the Android plugin. Set the JDK explicitly, and prefer a distribution that matches what developers use:

- uses: actions/setup-java@v4 with: distribution: temurin java-version: "17" cache: gradle - run: ./gradlew :app:assembleDebug --no-daemon

--no-daemon in CI avoids a daemon that outlives the job and masks a JDK change; caching keeps the build fast without it. If the runner image already has 17, printing java -version and ./gradlew -version as a first step turns a 20-minute debug loop into one log line.

Flutter and React Native wrappers

Both tools call Gradle through their own launchers, so the JDK they use comes from their configuration, not from the Android project alone. Flutter reads flutter config --jdk-dir and the JAVA_HOME of the shell that runs flutter build apk; a Flutter install pointed at Android Studio's embedded JBR 11 fails here. React Native's Gradle wrapper inherits JAVA_HOME from the terminal, so the export above applies unchanged.

bash
flutter config --jdk-dir="$JAVA_HOME" flutter doctor -v | grep -i "java version"

Bytecode target is a different setting

After the build runs, a second class of error appears if compileOptions targets an older level than the dependencies require: Dependency 'x' requires libraries and applications that depend on it to compile against version 34 or later of the Android APIs. That is a compileSdk problem, not a JDK problem, and raising jvmTarget will not touch it.

kotlin
android { compileSdk = 35 compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } }

Keep the two aligned: a project that compiles with Java 17 sources and runs on a 17 daemon has no ambiguity left for the next contributor.

Common Compilation/Runtime Mistakes & Version Gotchas

Changing jvmTarget and expecting the error to go away. jvmTarget sets bytecode for the compiler; the plugin check happens earlier, against the daemon JVM.

Exporting JAVA_HOME in one shell and building from another. IDEs, CI containers, and IDE terminals each have their own environment. Change the place that actually launches Gradle.

Leaving a stale org.gradle.java.home. A path from another machine, or one deleted during a JDK upgrade, fails with Java home supplied is invalid or silently falls back to an older JVM.

Using JAVA_HOME with a trailing slash or quoting error. Gradle accepts the path but some scripts append /bin/java twice. Use the unquoted, slash-free form that java_home prints.

Ignoring the Gradle version. AGP 8.8 requires Gradle 8.9; running Gradle 8.2 with a JDK 17 still fails, now with a different compatibility message. Update the wrapper with ./gradlew wrapper --gradle-version 8.9.

Assuming Java 21 works everywhere. AGP 8.x runs on 21 for most versions, but some older Kotlin or lint plugins break; when a build fails only on 21, testing 17 is a faster bisect than reading release notes.

Version floor. AGP 8.0 through 8.x require JDK 17; AGP 7.4 requires 11; jvmToolchain needs Gradle 6.7 or newer; --no-daemon is available in all current wrappers.

The check is a single version comparison, so the answer is always "which JVM did Gradle actually use". ./gradlew -version prints it in one line, and comparing that line between a working machine and a failing one ends the investigation. For the environment files that carry these values, the environment variable formatter keeps .env and shell exports consistent, and the JSON formatter helps when the JDK path is injected through a config file.

Official references: Java versions in Android builds and Gradle's toolchains for JVM projects.

Official references

primary documentation

The Java documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.