Gradle "No matching toolchains found" - Fix Toolchain Resolution

By Kaveh Alemi·Latchkey

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.

What this error means

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

gradle output

> Could not determine the dependencies of task ':app:compileJava'.
> No matching toolchains found for requested specification:
  {languageVersion=21, vendor=any, implementation=vendor-specific}
  for LINUX on x86_64.

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

The toolchain languageVersion does not match any JDK on the runner, and Gradle did not have one to auto-detect.

Auto-provisioning disabled or unreachable

If toolchain auto-download is off (or the download repository is unreachable in CI), Gradle cannot fetch the missing JDK and fails resolution.

How to fix it

Install the requested JDK in CI

Provision the exact JDK the toolchain asks for; setup-java exposes it for auto-detection.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
# Gradle auto-detects the installed JDK for the toolchain

Enable toolchain auto-provisioning

Let Gradle download the JDK via the foojay resolver plugin 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.
Add the foojay resolver so Gradle can auto-download when allowed.
Keep languageVersion aligned with a JDK you actually install.

Frequently asked questions

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.