Gradle Toolchain "No compatible toolchains found" (Detection) - Fix in CI

By Kaveh Alemi·Latchkey

Gradle could not find an installed JDK matching a Java toolchain request, and auto-download is off (or could not run), so it failed. Unlike a download failure, this is purely about detection - the matching JDK is not installed where Gradle looks, and Gradle was told not to fetch one.

What this error means

The build fails with No compatible toolchains found for request specification: {languageVersion=21, ...} (auto-detect false, auto-download false). A JDK 21 may even be installed, but Gradle is not detecting it.

gradle output

> No compatible toolchains found for request specification:
  {languageVersion=21, vendor=any, implementation=vendor-specific}
  (auto-detect false, auto-download false).

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 where Gradle detects

The toolchain languageVersion has no matching JDK in Gradle’s detected installations, so there is nothing to select.

Auto-detect/auto-download disabled

With org.gradle.java.installations.auto-detect=false (or auto-download off) Gradle will neither scan standard locations nor fetch a JDK, so an uninstalled toolchain simply fails.

How to fix it

Install the JDK and point Gradle at it

Provision the requested JDK and pass its path via the installations property.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
- run: ./gradlew build \
    -Dorg.gradle.java.installations.paths=$JAVA_HOME

Re-enable detection (or auto-download)

Let Gradle scan standard install locations, or allow it to download a matching JDK.

gradle.properties

# gradle.properties
org.gradle.java.installations.auto-detect=true
# optionally allow download (needs a resolver plugin):
org.gradle.java.installations.auto-download=true

How to prevent it

Install the toolchain JDK in CI and pass org.gradle.java.installations.paths.
Keep auto-detect on, or configure a download resolver, so toolchains can resolve.
Assert the toolchain resolves early (e.g. ./gradlew javaToolchains).

Frequently asked questions

What causes Gradle toolchain "No compatible toolchains found" (Detection)?

There are 2 common causes: requested jdk not installed where gradle detects and auto-detect/auto-download disabled. The toolchain languageVersion has no matching JDK in Gradle’s detected installations, so there is nothing to select.

How do I fix Gradle toolchain "No compatible toolchains found" (Detection)?

There are 2 fixes depending on which cause you have: install the jdk and point gradle at it and re-enable detection (or auto-download). Work through them in order, since the first is the most common.

What does Gradle toolchain "No compatible toolchains found" (Detection) actually mean?

The build fails with No compatible toolchains found for request specification: {languageVersion=21, ...} (auto-detect false, auto-download false).

How do I stop Gradle toolchain "No compatible toolchains found" (Detection) happening again?

Install the toolchain JDK in CI and pass org.gradle.java.installations.paths. 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.