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

> Fix Gradle "No matching toolchains found ... No locally installed toolchains match (and auto-detect/download disabled)" in CI - provision the requested JDK or enable toolchain auto-provisioning.

Source: https://latchkey.dev/learn/java-jvm/gradle-no-locally-installed-toolchains-match  
Updated: 2026-06-25

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.

## 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"
```

> Pin the JDK with `setup-java` and declare the toolchain in the build file. Relying on whichever JDK the runner image ships makes an image update a build break.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt