Gradle Toolchains

Three different Java versions take part in a build, and mixing them up is the cause of most "Java version" problems.

By default the toolchain is the daemon’s JVM: the official page says Gradle "uses the same Java toolchain for running Gradle itself and building JVM projects". That default is the root of the problems. A project that must compile with Java 21 breaks when a developer’s JAVA_HOME is 26 or 17; a build that wants Java 8 bytecode cannot run on Gradle 9 at all, which needs Java 17 or newer. Toolchains separate the two questions, so that Gradle runs on whichever recent Java it likes while the project says what it needs, in the build, where the team can see it and review it. The feature appeared in Gradle 6.7 (2020-10-14) and became stable in 7.0; the release history is at the end of the page.

Source: Gradle: Toolchains, introduction and Gradle: Compatibility Matrix, Java Runtime

The manual lists five mechanisms that tell Gradle which Java a JVM project uses. They are not exclusive, and the page recommends toolchains for most builds.

The --release flag is the only one that stops you from calling an API that does not exist in the target version, so the table’s last column is why the recommendation for strict cross-compilation is release, and for "build with the JDK the project says" is a toolchain; the two combine, which is the subject of the section on combining them below. The compatibility properties are legacy: the manual says to use them "only in cases where you need backward compatibility but cannot use toolchains". Maven has the same split: maven.compiler.release is its --release, and toolchains.xml is its toolchain (see Maven Compiling & Toolchains).

Source: Gradle: Toolchains, toolchains for projects and comparison table

A toolchain is declared in the java extension, which the java, java-library and application plugins (and the Groovy, Scala and Kotlin JVM plugins, which apply the Java plugin) provide. The only required property is the language version. In the tidepool build, every module asks for Java 21:

The same three lines go into tidepool-engine and tidepool-cli. (In a real multi-project build they belong in one convention plugin, which is the subject of Convention Plugins & Sharing Build Logic; they are repeated here so that each file is complete.) The root settings.gradle.kts declares the repository once and includes the three modules; the whole build ran from these files:

When the build runs, the official page lists what Gradle does for you: it configures every compile, test and Javadoc task of the project to use the toolchain, it detects the locally installed JDKs, it picks one that matches (any Java 21 here), and, if there is none and a download repository is configured, it downloads one. In 9.8.1 the compile task reports which JDK it used at the --info level:

The daemon ran on JDK 26, yet the class file has major version 65, which is Java 21: the compiler was the javac of the JBR 21 installation (javap is only reading the file; any JDK can). The task also records the toolchain as an input. Changing the language version of the module to 17 makes the next build recompile, and --info says why:

(The rest of the --info output is left out.) The manual adds that the Java major version, the vendor and the implementation, if given, "will be tracked as an input for compilation and test execution", which is why a toolchain change does not leave stale class files behind and why it also matters for the build cache (see Build Cache).

Which tasks use the toolchain? JavaCompile, Javadoc and Test, as before. Since Gradle 9.0.0 also JavaExec: the 9.0 upgrade guide says that, when the java-base plugin is applied, JavaExec "will instead default to the Java toolchain configured in the java extension", where earlier versions used the JVM of Gradle itself. A JavaExec task of the cli module that sets nothing shows it:

JvmInfo is a ten-line class in the cli module whose main prints "running on Java " + Runtime.version() + " (" + System.getProperty("java.vendor") + ")". Both DSLs printed the same (command ./gradlew --configuration-cache -q :tidepool-cli:runDefault):

The daemon is on Java 26 (./gradlew --version shows Launcher JVM: 26 and the daemon on the same JDK); the program ran on 21. On Gradle 8.14 the same task would have run on Java 26: the toolchain default for JavaExec did not exist (not run here).

Source: Gradle: Toolchains, using Java toolchains, Upgrading to 9.0: JavaExec uses the toolchain by default and Building Java projects: compiling with a toolchain

The language version is the only required property. A toolchain specification (JavaToolchainSpec) may add more, and each narrows the set of JDKs that match.

The JetBrains vendor and the matching("jetbrains") form both found the JBR 21 on this machine, in both DSLs. The other two lines are commented because nothing here could match them: there is no OpenJ9 JDK, and no GraalVM-capable JDK. With nativeImageCapable = true the build stops, and the message names every property of the specification, which is the quickest way to see what Gradle was looking for (the other messages are in the section on errors below):

A specification is valid in two cases: it is empty, or it sets languageVersion and optionally other properties. A vendor without a language version is rejected with an error (since Gradle 8.0, according to the manual, which also says that an unconfigured specification "selects the toolchain of the current build"). Setting only vendor = JvmVendorSpec.JETBRAINS produced:

The vendor and implementation, when given, are tracked as inputs like the language version. Which JDK a specification resolves to is decided by the rules in the sections that follow; the practical advice is to set the language version and nothing else unless the build really depends on a vendor (for example because only one has the compiler flags or the jlink modules the project needs), because every extra property reduces the number of machines on which the build works without a download.

Source: Gradle: Toolchains, selecting by vendor, by implementation, GraalVM native image, configuring toolchain specifications, JvmVendorSpec and Gradle 8.14 release notes

Before it can choose, Gradle has to find the installed JDKs. This is auto-detection, on by default, and the manual lists what it understands: operating-system specific locations (Linux, macOS, Windows), the conventional environment variable JAVA_HOME, the package managers Asdf-vm, Jabba and SDKMAN!, Maven toolchain specifications (~/.m2/toolchains.xml), and IntelliJ IDEA installations. Installations that do not exist or have no bin/java are ignored with a warning, not an error. The javaToolchains report of the project shows what was found and how:

(The output was printed in full except that the home directory is shown as ~.) Three things stand out. The two JBRs were found by "IntelliJ", because they live in ~/Library/Java/JavaVirtualMachines, one of the places that IntelliJ IDEA uses for the JDKs it manages; the JDK 26 is "Current JVM" because it is the JVM that runs the daemon, whichever way it was installed; and the header shows the state of the two switches, Auto-detection: Enabled and Auto-download: Disabled, the latter because of the gradle.properties of the examples. The task javaToolchains was added in Gradle 6.8. It is the first thing to run when a build says that no JDK matches.

Auto-detection can be turned off or extended with Gradle properties (set in gradle.properties or with -D on the command line; they belong to the daemon’s JVM, so changing them starts a new daemon, which the daemon page explains):

The custom locations extend the set; the manual says Gradle "does not prioritize custom toolchains over auto-detected toolchains". Four runs with different settings show what each one changes (-q javaToolchains, JDK paths shortened, the Options block and the fields other than the name, location and Detected by left out):

(The commands are written with ~ for the home directory for readability; the runs used full paths.) The JDK running the daemon is always in the list, even with auto-detection off, which is why a toolchain request for the daemon’s own Java version never needs a search. The last run used a daemon on JDK 26 (through org.gradle.java.home) and a client started with JAVA_HOME pointing at the JBR 21, and shows the JAVA_HOME source: it is detected even with auto-detection off, as the manual’s description of "conventional environment variable" implies. Using JAVA_HOME as a source is new in Gradle 9.0; the release notes say it makes the command line consistent with the IDEs, which did not look at it. Under 8.14 the same variable was not a detection source (not run here).

Source: Gradle: Toolchains, auto-detection, how to disable auto-detection, custom toolchain locations, viewing and debugging toolchains and Gradle 9.0.0 release notes

Several installations can match a specification, for example when a Java 17 request meets two vendors and a JRE. Gradle sorts all matching installations with a fixed sequence of criteria and takes the first:

The manual’s worked example has five Java 17 installations (Oracle JRE 17.0.1, Oracle JDK 17.0.0, Microsoft JDK 17.0.0, Microsoft JRE 17.0.1 and Microsoft JDK 17.0.1) and, with Gradle running on another Java, Gradle picks Microsoft JDK 17.0.1: the JDKs first, then Microsoft before Oracle, then the higher patch level. This machine has one JDK per version, so the order could not be shown with real output; the first rule is visible in the runs above (a request for 26 resolves to "Current JVM") and the sorting itself is taken from the manual and is therefore "not run here". Two consequences are worth remembering. A patch update of a JDK changes which JDK is chosen, silently. And two developers with different vendors installed build with different JDKs unless the vendor is pinned in the specification.

Source: Gradle: Toolchains, toolchain installations precedence

Auto-detection can fail in three ways, and each has its own message. All of them were produced in the tidepool build by changing the toolchain of the model module and running ./gradlew :tidepool-model:compileJava. (They were run without --configuration-cache: with it on, the same text appears but prefixed with a line that says that the configuration cache state could not be stored, because Gradle resolves the compiler while it stores the entry. The first message is shown that way below.) The first asks for a vendor that is not installed:

Auto-provisioning was off, so the message ends with "Toolchain auto-provisioning is not enabled." A request for Java 11, which is not installed, gave the same text with languageVersion=11, vendor=any vendor in the specification. The second failure appears when auto-download is on (the default) but nothing says where to download from. This was run with -Dorg.gradle.java.installations.auto-download=true and Java 11; Gradle stopped before trying any download:

The sentence "Toolchain download repositories have not been configured." is the one to recognise: since Gradle 8.0 there is no default provisioner, so a build that worked in 7.x because it silently downloaded from Adoptium needs a repository declaration now (next section but one). The third failure is the configuration-cache variant of the first, shown for completeness (Java 11 again, with --configuration-cache):

The last line is the same cause. The cache report says that the compiler property could not be stored because it could not be resolved; the fix is the same, not a cache setting. The message about invalid specifications was shown above.

Source: Gradle: Toolchains, auto-detection, auto-provisioning and Gradle 8.0 release notes

When no installed JDK matches, Gradle can download one. This is auto-provisioning, and it needs two things: org.gradle.java.installations.auto-download not set to false (the default is true), and at least one toolchain download repository declared in settings.gradle(.kts). The rules of the manual are short: the JDK goes to the jdks directory of the Gradle User Home, where it becomes one of the JDKs that auto-detection finds for every later build; Gradle only downloads GA releases (no early-access builds); and provisioning only fills gaps, it never updates a JDK it has already installed, even if a newer minor version exists. To remove one, delete its directory from jdks and stop the daemon, because the daemon caches the toolchain paths (the ./gradlew --stop advice of the manual).

Since Gradle 8.0 there is no default repository. Gradle 7.6 (2022-11-25) introduced toolchain resolver plugins, which map a specification to a download URL, and the 8.0 release notes say that "there is no longer a default toolchain provisioner": you declare at least one, usually through the Foojay Toolchains plugin, which uses the Foojay Disco API to find JDK distributions. There are two plugins on the Plugin Portal, both at version 1.0.0 on 2026-10-16. The convention plugin does all the configuration by being applied:

The plain plugin only provides the resolver; you register it in a toolchainManagement block, which is what you need when several repositories are configured, or when their order, or credentials, matter:

Both forms were applied to the tidepool build in both DSLs and run with the JDK 21 toolchain. They only matter when a JDK is missing, so the build behaved as before (BUILD SUCCESSFUL, the JBR 21 was used, nothing was downloaded; the same file also configures dependencyResolutionManagement and include as above, omitted here). With auto-download switched off in gradle.properties, a request for Java 11 still stopped with "Toolchain auto-provisioning is not enabled.", exactly as in the section on errors: the repositories are consulted only when the property allows it. That is the setting that keeps CI builds honest. The actual download of a JDK was not run here: it would fetch a JDK from the network into the Gradle User Home, which these examples avoid on purpose.

In the toolchainManagement block, the jvm block holds the Java configuration, javaRepositories defines named repositories, and the resolverClass links each to the plugin that provides it. The order of the declarations matters: Gradle asks the repositories from the first to the last and downloads from the first that has a match. Repositories can carry the same credentials and authentication as dependency repositories (the manual’s example uses a fictitious MadeUpResolver with user name, password and digest authentication; that example was not run here, because it needs a resolver plugin that does not exist). Since Gradle 8.8, an error thrown by one resolver no longer stops the search: Gradle tries the next one.

Two cautions come with downloading JDKs. The Foojay API is a third-party service, and the JDK it points to is run on every build machine, so it is a link in the supply chain (compare Supply-Chain Security); teams that cannot accept that install the JDKs in the CI image and set org.gradle.java.installations.auto-download=false, or configure a resolver of their own for an internal mirror. And a download makes the first build on a fresh machine slow and dependent on the network, which is also why the examples on this page forbid it.

A toolchain chooses the compiler; options.release chooses the language level and the API that the compiler lets the code see. Using both is the recommended way to compile with a recent JDK and still produce bytecode for an older Java: the manual’s example compiles with Java 17 and targets 11. In the tidepool build the toolchain is 21 and the root build file sets the release to 17 for every module:

(Configuring subprojects from the root is a shortcut for a small example, not a recommendation; the build logic belongs in a convention plugin.) With it, javap reports major version: 61, which is Java 17, for classes that the JBR 21 compiled. The reason this combination matters shows in what happens without it. The next tasks run the unit test and a small program on a Java 17 launcher (their definition is in the section on tasks below), but the classes had been compiled by JDK 21 with the default target, 21. Both failed with the exception that every toolchain user eventually meets, run with ./gradlew --configuration-cache :tidepool-cli:runOn17 and :tidepool-model:testsOn17:

(Both outputs are trimmed; the second ends before the usual list of hints.) The compiler of the toolchain 21 wrote class files of version 65, and the launcher 17 reads up to 61. Compiling with options.release = 17 fixes it, because the class files are now version 61, and it also makes the compiler refuse APIs newer than Java 17. The same build with the release raised above the toolchain fails at compile time:

This one ran with the model’s toolchain at 17 and release = 21. The message comes from javac of the toolchain, which knows nothing about Java 21 (the report line of the Gradle problems API is left out). Setting sourceCompatibility and targetCompatibility instead of the release would not have stopped a call to a Java 21 method when compiling with JDK 21, which is the point of the table above.

Source: Gradle: Toolchains, combining toolchains and the --release flag

The project toolchain is a default. Each task that runs a Java tool has a property for it, and the javaToolchains extension, a JavaToolchainService, creates the value from a specification. Three tools exist:

Depending on the task a JRE may be enough (a launcher) or a JDK is required (the compiler); Gradle prefers an installed JDK over a JRE when both satisfy the requirements. The properties are lazy Property values (see Lazy Configuration & Providers), so nothing is resolved, and nothing is provisioned, until the task needs it.

The most common use is to run tests on a different Java than the one the code is compiled for. The model module has a test that checks the Java it runs on (it prints the version and asserts that it matches a system property), and one Test task for each launcher:

The cli module has the same for an application, a JavaExec task that overrides the default launcher (the manual’s example is called runOn17 too):

With options.release = 17 in place, one run of ./gradlew --configuration-cache :tidepool-model:test :tidepool-model:testsOn17 :tidepool-cli:runOn17 (identical in both DSLs, output shortened to the interesting tasks) printed:

The default test task ran on the JBR 21 and testsOn17 on the JBR 17, in a build whose daemon runs on 26; the program ran on 17. A second run reused the configuration cache entry and reported the task as up to date. (testLogging { showStandardStreams = true } is only there to print the version; the test also asserts it. The tests, the JUnit platform and the test reports are the subject of Testing JVM Projects.) The same mechanism lets a module compile with an older JDK than the rest, or build its Javadoc with a newer one. In the engine module, the compile task was given Java 17 and the Javadoc task Java 21 (the project toolchain stays 21):

(./gradlew --configuration-cache :tidepool-engine:compileJava :tidepool-engine:javadoc --info, filtered with grep for the lines shown; the last Starting process line is cut after the name of the executable, and javap on the engine’s class file said major version: 61, since the release flag is still 17.) The engine compiled with the 17 compiler while its dependency, the model module, compiled with 21, and Javadoc was run by the javadoc executable of the JBR 21. The Groovy DSL form of the same two tasks gave the same two Compiling with toolchain lines.

A plugin or task that runs a Java tool should follow the same convention as the core plugins: default to the project’s toolchain, and let the user override it per task. The manual’s pattern is a JavaLauncher property marked @Nested (so that the task responds to a toolchain change), whose convention is the launcher of the project’s java extension. The following task prints what it was given. It is declared in the cli module, with two registrations, one with the default and one with an override, and extends the pattern with the path-based properties of the previous section, wired lazily:

(./gradlew --configuration-cache :tidepool-cli:showDefaultToolchain :tidepool-cli:showCustomToolchain, both DSLs; the second run reused the configuration cache entry, so the task type is configuration-cache compatible. The project reference in init is a configuration-time use, which is allowed.) In short: the launcher property is @Nested "to make sure the task is responsive to toolchain changes", as the manual says; the user needs to configure the toolchain once, at the project level, and individual tasks may override it; and the convention comes from JavaToolchainService.launcherFor(toolchain), which receives the specification of the java extension. When a task needs a toolchain without the java plugin applied, the service can be used directly. If an unconfigured specification is given to it, it always returns the tool of the toolchain that is running Gradle (for example javaToolchainService.launcherFor({})). The java plugin is applied automatically by the core Groovy and Scala plugins and by the Kotlin plugin, so for JVM projects it is safe to assume that it is there. A plugin that works with toolchains also has to be built for it: since 8.0, precompiled script plugins use the project’s toolchain (Java 8 if none), and the 9.0 upgrade guide says that the ValidatePlugins task fails unless the jvm-toolchains plugin is applied, which the Java Library plugin and the other JVM plugins do. How to write tasks and plugins is in Writing Custom Tasks and Binary Plugins.

Source: Gradle: Toolchains, toolchains for plugin authors, Gradle 8.0 release notes and Upgrading to Gradle 9.0.0: ValidatePlugins

The toolchain of the project and the JVM of the daemon are independent, and the daemon has its own, declarative file. ./gradlew updateDaemonJvm writes gradle/gradle-daemon-jvm.properties with the language version, optionally the vendor, and download URLs; Gradle then starts a daemon on a matching JDK, which it finds with the same auto-detection and, if necessary, downloads with the same auto-provisioning described above (the org.gradle.java.installations.* properties apply to the daemon too). The criteria take precedence over org.gradle.java.home and JAVA_HOME. The feature appeared in Gradle 8.8 as an incubating preview (called "Gradle daemon JVM configurable via toolchain" in the release notes), became stable in 9.2.0 (2025-10-29), and 8.14 added native-image capability to it. All the runs, the file format, the vendors and the messages are on The Gradle Daemon and are not repeated here. In a build that uses both, a typical split is: the daemon on the newest LTS the team likes (so that Gradle itself is fast and supported), and the toolchain on the Java version of the product. The ./gradlew --version lines Launcher JVM and Daemon JVM, together with javaToolchains, tell which of the three is which.

Source: Gradle: Gradle Daemon, Daemon JVM criteria, Gradle 8.8 release notes and Gradle 9.2.0 release notes

Toolchains work through the java extension, so every JVM language plugin that applies the Java plugin shares them. The manual’s statement: "Toolchain support is available in the Java plugins and for the tasks they define."

Source: Gradle: Toolchains, using Java toolchains, Kotlin: Gradle Java toolchains support and Gradle 8.0 release notes

The compatibility matrix of the user manual lists, for each Java version, the first Gradle release that supports it as a toolchain (to compile, test and run code) and the first that can run Gradle on it. The rows that matter today:

Gradle 9.8.1 needs Java 17 to 27 to run; Java 28 and later is not yet supported. Toolchains are what makes the first column useful beyond the second: the official page says that any fully supported Java can be used for compilation or testing, that Java 6 and later can be used for compilation, Java 8 and later for running tests, and that "the latest Java version may only be supported for compilation or testing, not for running Gradle". A project that compiled with Java 8 or 11 on Gradle 8.x keeps doing so on Gradle 9 through a toolchain, as the 9.0 upgrade guide says. A Java 8 toolchain was not run here: only JDKs 17, 21 and 26 are installed on the machine and nothing may be downloaded.

Source: Gradle: Compatibility Matrix, Java Runtime and Upgrading to Gradle 9.0.0: JVM 17 or higher is required

IDE. IntelliJ IDEA (Settings, Build, Execution, Deployment, Gradle, "Gradle JVM") and Eclipse (Preferences, Gradle, "Gradle JDK") each have a setting for the JVM that runs Gradle. It affects the daemon, "not how your code is compiled", unless the build declares no toolchain, in which case the fallback may differ between team members. The manual’s advice is to align the IDE’s Gradle JVM with the command line (JAVA_HOME or the default Java), and to declare a toolchain so that compilation does not depend on the IDE at all. IntelliJ-downloaded JDKs are themselves a detection source (the "IntelliJ" entries in the report above). The IDE settings were not run here. See CI & IDE Integration.

CI. Make the JDKs part of the image, and set org.gradle.java.installations.auto-download=false so that a missing JDK is an immediate, explained failure (the first error above) instead of a download in the middle of a build, or give the build a Foojay-style repository that points at an internal mirror. In both cases keep the javaToolchains report in the build log when debugging. A cached provisioned JDK lives in jdks/ of the Gradle User Home, so the directory belongs with the other things to cache (see Directories & Logging).

Containers. The manual lists one limitation: Gradle may detect toolchains incorrectly when it runs in a JVM compiled against musl, the C library of most Alpine Linux distributions, because such a JVM can override LD_LIBRARY_PATH, which then leaks into the forked Java processes. Using several toolchains is therefore discouraged on musl; a single toolchain (the JVM running Gradle) is fine. The advice is to use another distribution, such as Ubuntu, for the build image. This was not run here.

Source: Gradle: Toolchains, IDE settings, limitations and JAVA_HOME

The links for the first two columns: Ant: Compiling Java and Ant: Running Programs; Maven Compiling & Toolchains, and for Surefire Maven: Testing with Surefire. The shared comparison is in Comparing Ant, Maven and Gradle, and what carries over when a Maven build moves to Gradle in Migrating from Maven. The main difference stays the one the Maven page states: in Gradle the requirement is in the build file and a missing JDK can be downloaded; in Maven the JDK has to be installed and described on each machine.

Source: the release notes 6.7, 6.8, 7.0, 7.6, 8.0, 8.8, 8.14, 9.0.0, 9.1.0, 9.2.0, 9.4.0 and 9.8.0

Gradle 8.14.6 was not available here, so this list comes from the release notes and upgrade guides and is not run here.

Source: Upgrading from Gradle 8.14 to 9.0, Upgrading to Gradle 9.0.0 and the release notes above

Gradle in Action (Muschko, Manning 2014, Gradle 1.7) sets the Java level of a build with sourceCompatibility and targetCompatibility in the Java plugin chapters and takes the compiler from whichever JDK is on the path or in JAVA_HOME; the IDE plugins' jdkName setting plays the same role for project files. None of the toolchain features existed: toolchains (6.7), vendor selection (6.8), automatic downloads (7.6) and the javaToolchains report (6.8) are all later, and the manual now recommends toolchains and, for strict cross-compilation, --release, and calls the compatibility properties a fallback. The book’s requirement of "JDK 1.5 or later" to run Gradle is also long gone: Gradle 9 needs Java 17 or later to run, and older Java versions are reachable only through toolchains. The book’s page numbers were not checked; the statement follows the research notes behind this section.