GitHub Actions gradle/actions/setup-gradle Fails to Download the Distribution

By Daniel Zoghalchali·Latchkey

gradle/actions/setup-gradle could not obtain the Gradle distribution. Most often this is a transient download failure from the distribution host; sometimes it is a wrapper checksum mismatch or an invalid gradle-version.

What this error means

The setup-gradle (or first gradlew) step fails while downloading the Gradle distribution, with a network read timeout or a checksum verification error. Re-running frequently succeeds, which points to a transient fetch.

Exception in thread "main" java.io.IOException: Downloading from
https://services.gradle.org/distributions/gradle-8.7-bin.zip failed: timeout

Common causes

Transient distribution download failure

Fetching the Gradle distribution over the network can time out or reset during a brief services.gradle.org or registry outage, failing the step through no fault of the config.

Wrapper checksum or version mismatch

A distributionSha256Sum in gradle-wrapper.properties that does not match, or a non-existent gradle-version, makes the download fail validation deterministically.

How to fix it

Pin a valid version and let it cache

- uses: gradle/actions/setup-gradle@v4
  with:
    gradle-version: wrapper   # use the version from gradle-wrapper.properties

Retry transient downloads; fix real checksum errors

1. Re-run the job when the failure is a timeout or connection reset on the distribution download.
2. If it is a checksum mismatch, correct distributionSha256Sum in gradle-wrapper.properties.
3. Confirm the requested gradle-version actually exists.

How to prevent it

• Use gradle-version: wrapper so the version comes from the committed wrapper.
• Keep a correct distribution checksum in gradle-wrapper.properties.
• Retry transient distribution-download failures rather than churning config.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions