Gradle Toolchain "Could not download" JDK - Fix in CI

By Kaveh Alemi·Latchkey

Gradle tried to auto-provision a JDK for a Java toolchain but could not download it. The foojay resolver reached out for the JDK and the fetch failed - usually a network-restricted runner or an unreachable download endpoint.

What this error means

Configuration fails with Could not download <jdk-archive> / Unable to download toolchain matching ... while resolving a languageVersion toolchain. The build never compiles because the toolchain JDK is missing.

gradle output

> Could not resolve all files for configuration ':app:compileClasspath'.
   > Could not download jdk-21.0.2+13 (org.example:jdk:21).
      > Unable to download toolchain. Read timed out.

Common causes

Restricted or offline runner

CI that blocks outbound access to the JDK download host cannot auto-provision the toolchain JDK, so the fetch times out or is refused.

Transient download failure

A blip or a slow endpoint times out the one-time JDK download. A re-run with a warm Gradle cache often succeeds.

How to fix it

Pre-install the JDK and let Gradle detect it

Install the toolchain JDK with setup-java so auto-download is unnecessary.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
# Gradle detects the installed JDK; no download needed

Cache or mirror toolchains for restricted CI

Cache ~/.gradle so a downloaded JDK is reused, or point auto-provisioning at an internal mirror.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.gradle/jdks
    key: gradle-jdks-${{ hashFiles('**/build.gradle*') }}
# or set org.gradle.jvm.toolchain.install.* to an internal source

How to prevent it

Pre-install toolchain JDKs with setup-java on restricted runners.
Cache ~/.gradle/jdks so a provisioned JDK is reused.
Mirror JDK downloads internally for offline CI.

Frequently asked questions

What causes "Toolchain JDK download failed"?