Gradle wrapper "Verification of Gradle distribution failed" checksum in CI

By Kaveh Alemi·Latchkey

When distributionSha256Sum is set, the wrapper verifies the downloaded zip against that hash. A mismatch means the zip differs from the pinned checksum, from a version bump, a proxy rewriting the download, or a corrupt transfer.

What this error means

The wrapper fails with "Verification of Gradle distribution failed!" printing the expected and actual SHA-256 of the downloaded zip.

Verification of Gradle distribution failed!

Your Gradle distribution may have been tampered with.
Confirm that the 'distributionSha256Sum' property in your gradle-wrapper.properties file is correct.

  Distribution Url: https://services.gradle.org/distributions/gradle-8.7-bin.zip
  Download Location: /home/runner/.gradle/wrapper/dists/gradle-8.7-bin/...
  Expected checksum: '544c35d6bd...'
  Actual checksum:   'e0f0f4f2a1...'

Common causes

The pinned checksum does not match the URL

The distributionUrl version changed but distributionSha256Sum was not updated, so the correct zip fails the stale hash.

A proxy or corrupt download altered the zip

A TLS-inspecting proxy or a truncated download produced a zip whose hash differs from the official one.

How to fix it

Pin the correct checksum for the version

1. Get the official SHA-256 for the exact distributionUrl version.
2. Update distributionSha256Sum in gradle-wrapper.properties.
3. Re-run so the verification passes.

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
distributionSha256Sum=544c35d6bd849ae8a5ed0bcea39ba677dc40f49df7d1835561582da2009b961d

Rule out a tampering proxy

If the checksum is correct, a proxy is rewriting the zip. Download through a trusted path or mirror the official distribution internally.

How to prevent it

• Update distributionSha256Sum whenever you bump the Gradle version.
• Mirror the official distribution so proxies do not alter it.
• Keep the wrapper distribution cached so it is verified once.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation