Gradle Wrapper "Checksum ... does not match" - Fix in CI

By Daniel Zoghalchali·Latchkey

The Gradle wrapper downloaded the distribution but its SHA-256 did not match the distributionSha256Sum pinned in gradle-wrapper.properties. Either the configured checksum is wrong, or the download was corrupted.

What this error means

The first ./gradlew invocation aborts with Verification of Gradle distribution failed!, printing the configured checksum and the actual checksum of the downloaded zip.

gradle output

Verification of Gradle distribution failed!
Your Gradle distribution may have been tampered with.
Confirm that the configured checksum 'abc123...' (from gradle-wrapper.properties)
matches the checksum 'def456...' (from the downloaded distribution).

Common causes

Wrong distributionSha256Sum pinned

The checksum in gradle-wrapper.properties does not correspond to the distribution at distributionUrl - a copy/paste error or a version bump that updated the URL but not the sum.

Corrupted or proxied download

A truncated download, or a proxy that rewrote the zip, produces a different checksum than the published one.

How to fix it

Set the correct published checksum

Use the official SHA-256 for the exact distribution version from gradle.org.

gradle-wrapper.properties

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

Re-download cleanly or regenerate the wrapper

Clear the cached wrapper and let Gradle re-fetch, or regenerate the wrapper to repin the sum.

Terminal

rm -rf ~/.gradle/wrapper/dists
./gradlew wrapper --gradle-version 8.8 --gradle-distribution-sha256-sum <sha256>

How to prevent it

Pin distributionSha256Sum to the official value, mirror the distribution internally for high-volume CI, and avoid proxies that rewrite binary downloads.

Frequently asked questions

What causes ""Verification of Gradle distribution failed!""?