skip to content

A teammate reports 'Verification of Gradle distribution failed!' after pulling your branch. How do you diagnose and resolve it?

level: middleimportance: should knowfreq 28%

answer

  1. expected vs actual sum in the error
  2. #1 cause: version/type bumped, sum not updated
  3. clear ~/.gradle/wrapper/dists cache
  4. proxy/mirror may serve wrong artifact
  5. don't delete the sum to 'fix' it

basics

~20 s

It means the downloaded distribution's SHA-256 didn't match distributionSha256Sum. Check whether distributionUrl and the pinned sum are consistent (right version/type), clear the cached partial download, and re-pin via the wrapper task if the sum was wrong.

solid answer

~40 s

The error means the wrapper computed the SHA-256 of the downloaded archive and it didn't equal `distributionSha256Sum`. Diagnose by reading the error: it prints the expected sum (your pin) and the actual sum (what was downloaded). Common causes, in order: (1) `distributionUrl` and `distributionSha256Sum` are inconsistent — someone bumped the version or switched bin/all but didn't update the sum; (2) a corrupted/partial download in `~/.gradle/wrapper/dists/`; (3) a proxy/mirror serving a different artifact; (4) genuine tampering. Resolution: confirm the pinned sum matches the *official* sum for the exact `distributionUrl`. If they're inconsistent, re-run `./gradlew wrapper --gradle-version <v> --gradle-distribution-sha256-sum <official>` and commit. If the pin is correct, delete the cached distribution under `~/.gradle/wrapper/dists/<...>` to force a clean re-download. Never 'fix' it by just deleting the sum — that removes the protection.

code

bash · 5 lines
bash
# Force a clean re-download after confirming the pin is correct
rm -rf ~/.gradle/wrapper/dists/gradle-8.7-bin/
./gradlew --version
# If pin itself was wrong, re-pin instead:
# ./gradlew wrapper --gradle-version 8.7 --gradle-distribution-sha256-sum <official-sum>

go deeper

for a junior

Recognize it's a checksum mismatch and that the sum and URL should match the same version.

for a middle

Walk the diagnostic checklist (consistency, cache, proxy, tampering) and resolve without deleting the protection.

for a senior

Distinguish a benign stale-pin from a true tampering signal and drive a clean re-pin via the wrapper task.

for a principal

Establish that version bumps regenerate URL+sum together and that unexplained mismatches escalate as supply-chain incidents.

## What the error means The wrapper downloaded the distribution archive, computed its SHA-256, and it didn't match the pinned `distributionSha256Sum`. Gradle fails closed and refuses to unpack/run it. The message includes both the **expected** (your pinned value) and the **actual** (computed) sums — read them, they tell you a lot. ## Diagnostic checklist 1. **URL/sum consistency.** Open `gradle-wrapper.properties`. Does `distributionUrl` point to the same version *and* archive type (`-bin.zip` vs `-all.zip`) that the pinned sum was generated for? A version bump or type switch without re-pinning is the #1 cause. Cross-check the pinned value against Gradle's official published checksum for that exact URL. 2. **Corrupted/partial cache.** Interrupted downloads can leave bad bytes under `~/.gradle/wrapper/dists/`. Delete that distribution's folder to force a fresh download. 3. **Proxy/mirror interference.** A corporate proxy, internal mirror, or CDN may be serving a different artifact (or an HTML error page). Confirm the URL is reachable and returns the real ZIP. 4. **Genuine tampering.** If the URL is correct, the cache is clean, and the official sum still doesn't match what's downloaded — treat it as a security incident, not a nuisance. ## Resolution ```bash # If the pin was simply stale/wrong: re-pin from the official value and commit ./gradlew wrapper --gradle-version 8.7 \ --gradle-distribution-sha256-sum <official-sum-for-8.7-bin> # If the pin is correct but the cache is bad: clear and retry rm -rf ~/.gradle/wrapper/dists/gradle-8.7-bin ./gradlew --version ``` ## The wrong fix Deleting the `distributionSha256Sum` line makes the error disappear by *removing the integrity check entirely*. That's the opposite of what you want — the failure was the safeguard doing its job. Fix the cause (consistency or cache), not the symptom. ## Prevention Make version bumps go through `./gradlew wrapper` so URL and sum are always written together, and review the diff of both lines in the PR.

  • Why is deleting distributionSha256Sum the wrong fix?
    It removes the integrity check entirely. The failure was the safeguard working; you should fix the URL/sum consistency or the corrupted cache instead.
  • The error shows the actual download is an HTML page hash, not a ZIP — what does that suggest?
    A proxy/mirror or an expired URL is serving an error page instead of the archive, so the bytes (and thus the hash) are wrong. Fix connectivity/URL rather than the sum.

saying these in an interview costs you the question

  • Removing distributionSha256Sum to make the error go away.
  • Re-pinning by hashing whatever just downloaded without checking the official value.
  • Ignoring a genuine mismatch where URL is correct and cache is clean — that's a security signal.

context

resolving links…