Java Toolchain Auto-Detection Failed - No Matching JDK in CI

The build tool searched the runner for a JDK matching the toolchain language version and found none. No matching JDK is installed, and auto-download is disabled or blocked by the network.

What this error means

The build fails configuring the toolchain with No matching toolchains found for requested specification: {languageVersion=21} and a note that auto-detection/auto-download did not locate a JDK.

gradle output

* What went wrong:
> No matching toolchains found for requested specification:
  {languageVersion=21, vendor=any, implementation=vendor-specific}.
  Toolchain auto-provisioning is not enabled.

Common causes

No JDK of the requested version installed

Auto-detection scans installed JDKs. If none matches the toolchain languageVersion, and auto-download is off, there is nothing to select.

Auto-provisioning disabled or network-blocked

Toolchain download is off (no resolver configured) or the runner cannot reach the JDK download endpoint, so Gradle cannot fetch a matching JDK.

How to fix it

Provision the JDK so detection succeeds

Install the requested JDK with setup-java; the toolchain then auto-detects it.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
# Gradle toolchain {languageVersion = 21} now matches the installed JDK

Enable a toolchain resolver for auto-download

Add the foojay resolver so Gradle can download a matching JDK when none is present.

settings.gradle.kts

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

How to prevent it

Install the toolchain JDK with setup-java in CI, or configure the foojay resolver, so toolchain detection always finds a match.