# Gradle "No matching toolchains found" - Fix Toolchain Resolution

> Fix Gradle "No matching toolchains found for requested specification" in CI - the requested JDK is not installed and auto-provisioning/auto-detect could not supply it.

Source: https://latchkey.dev/learn/java-jvm/jdk-toolchain-no-matching-toolchains  
Updated: 2026-06-25

Gradle’s Java toolchain feature was asked for a specific JDK (e.g. version 21) and could not find one installed, nor provision it. The build cannot select a compiler that matches your `languageVersion`.

## 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 matching toolchains found"?

There are 2 common causes: requested jdk not installed and auto-provisioning disabled or unreachable. The toolchain languageVersion does not match any JDK on the runner, and Gradle did not have one to auto-detect.

### How do I fix Gradle "No matching toolchains found"?

There are 2 fixes depending on which cause you have: install 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 matching toolchains found" actually mean?

The build fails during configuration with No matching toolchains found for requested specification: {languageVersion=21, ...} and a note about auto-detection or auto-download.

### How do I stop Gradle "No matching toolchains found" happening again?

Provision the toolchain JDK in CI with setup-java. The prevention section lists 3 changes that keep it from recurring.

---

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