Gradle Wrapper "Could not download/install" Distribution in CI

By Kaveh Alemi·Latchkey

The Gradle wrapper tried to download the Gradle distribution it is pinned to and failed - usually a transient network blip fetching the zip, sometimes a bad distributionUrl or a checksum mismatch.

What this error means

The very first ./gradlew invocation fails before any build logic, while downloading or unpacking the distribution zip named in gradle-wrapper.properties.

gradle output

Downloading https://services.gradle.org/distributions/gradle-8.8-bin.zip
Exception in thread "main" java.io.IOException: Downloading from
https://services.gradle.org/distributions/gradle-8.8-bin.zip failed:
timeout (Read timed out)

Common causes

Transient network failure fetching the zip

The distribution download is a one-time network fetch. A blip or a slow mirror times out, and the wrapper aborts. Re-running often succeeds.

Bad distributionUrl or checksum mismatch

A wrong URL (typo, removed version) or a distributionSha256Sum that does not match the downloaded zip causes a hard, non-transient failure.

How to fix it

Cache the wrapper distribution

Cache ~/.gradle/wrapper so the distribution is downloaded once and reused across jobs.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/wrapper
      ~/.gradle/caches
    key: gradle-${{ hashFiles('**/*.gradle*', 'gradle/wrapper/gradle-wrapper.properties') }}

Verify the distributionUrl and checksum

Confirm the pinned version exists and the checksum matches.

gradle-wrapper.properties

# gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip
distributionSha256Sum=<sha256 from gradle.org>

How to prevent it

Cache ~/.gradle/wrapper and ~/.gradle/caches in CI.
Pin the distribution with a verified distributionSha256Sum.
Mirror the Gradle distribution internally for high-volume pipelines.

Frequently asked questions

What causes "Wrapper distribution failed"?

The distribution download is a one-time network fetch. A blip or a slow mirror times out, and the wrapper aborts. Re-running often succeeds.

How do I fix Wrapper distribution failed?

Cache ~/.gradle/wrapper so the distribution is downloaded once and reused across jobs.

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.