Gradle "No locally installed toolchains match" - Fix JDK Toolchain in CI

By Kaveh Alemi·Latchkey

Your build asked for a specific Java toolchain (e.g. language version 21) and Gradle could not find a matching JDK on the runner. With auto-detection or auto-download disabled, no JDK satisfied the request, so the build cannot select a compiler.

What this error means

The build fails with No matching toolchains found for the requested specification and No locally installed toolchains match (and toolchain auto-provisioning is not enabled), naming the requested version (e.g. {languageVersion=21, ...}).

gradle output

* What went wrong:
Could not determine the dependencies of task ':app:compileJava'.
> Failed to calculate the value of task ':app:compileJava' property 'javaCompiler'.
   > No matching toolchains found for the requested specification:
     {languageVersion=21, vendor=any, implementation=vendor-specific}.
     No locally installed toolchains match and toolchain download repositories
     have not been configured.

Diagnose it: which JDK is the build actually using?

JVM builds resolve a toolchain from several sources, and the one on PATH is often not the one compiling your code. A version mismatch surfaces as an unsupported class file version rather than as a toolchain error.

Terminal

java -version 2>&1
echo "JAVA_HOME=$JAVA_HOME"
./gradlew -q javaToolchains 2>/dev/null || mvn -v

# class file 65 = Java 21, 61 = Java 17, 55 = Java 11
javap -verbose <SomeClass>.class | grep "major version"

Common causes

Requested JDK not installed on the runner

The java.toolchain { languageVersion = 21 } needs a JDK 21 present. If CI only provisioned JDK 17, no local toolchain matches.

Auto-provisioning disabled with no download repo

Toolchain download requires a configured provisioning repository (e.g. the Foojay resolver) and network access. Disabled or unconfigured, Gradle cannot fetch the missing JDK.

How to fix it

Provision the requested JDK in CI

Install the JDK the toolchain asks for so a local toolchain matches. setup-java exposes it for auto-detection.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'   # satisfies languageVersion = 21

Enable toolchain auto-provisioning

Add the Foojay toolchains resolver so Gradle can download a matching JDK when none is installed.

settings.gradle.kts

// settings.gradle.kts
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
}

How to prevent it

Provision the toolchain JDK in CI with setup-java, and let Gradle auto-detect it.
Add the Foojay resolver so a missing toolchain can be downloaded.
Keep languageVersion aligned with a JDK that CI actually installs.

Frequently asked questions

What causes Gradle "No locally installed toolchains match"?

There are 2 common causes: requested jdk not installed on the runner and auto-provisioning disabled with no download repo. The java.toolchain { languageVersion = 21 } needs a JDK 21 present.

How do I fix Gradle "No locally installed toolchains match"?

There are 2 fixes depending on which cause you have: provision the requested jdk in ci and enable toolchain auto-provisioning. Work through them in order, since the first is the most common.

What does Gradle "No locally installed toolchains match" actually mean?

The build fails with No matching toolchains found for the requested specification and No locally installed toolchains match (and toolchain auto-provisioning is not enabled), naming the requested version (e.g.

How do I stop Gradle "No locally installed toolchains match" happening again?

Provision the toolchain JDK in CI with setup-java, and let Gradle auto-detect it. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.