skip to content

What happens during a build when a recorded checksum no longer matches a downloaded artifact, and how would you diagnose it?

level: seniorimportance: should knowfreq 38%

answer

  1. hard fail, no warn-and-continue
  2. report: expected vs actual + repo
  3. build/reports/dependency-verification HTML
  4. never blindly --write to 'fix' a mismatch
  5. triage: my change? re-publish? tampering?

basics

~20 s

Gradle fails the build with a 'Dependency verification failed' error naming the artifact, the expected checksum, and the actual one. You diagnose by checking whether the version/repo changed, the artifact was re-published, or something tampered with it.

solid answer

~60 s

When the computed hash differs from the recorded one, Gradle aborts resolution and prints a verification report — for each offending artifact it shows the expected checksum (from `verification-metadata.xml`), the actual computed value, the algorithm, and the source repository. The build does not proceed: you can't compile or run with an unverified artifact. Diagnosis is a triage: (1) Did *you* change the dependency version or add a new one? Then the metadata is simply stale — regenerate with `--write-verification-metadata`. (2) Did the upstream re-publish the same coordinates with different bytes (which violates immutability but happens)? Verify against the publisher's official checksum. (3) Did a mirror/proxy, cache, or network path serve different bytes? That's the alarming case — a potential supply-chain compromise — and you must *not* blindly regenerate, because regenerating would launder the tampered bytes into 'trusted'. The discipline is: investigate the source of the mismatch before touching the metadata. A clean local cache (`--refresh-dependencies`) and comparison against an independent source help confirm whether it's benign drift or tampering.

code

bash · 5 lines
bash
# Rule out a poisoned local cache: re-fetch from the repository
./gradlew build --refresh-dependencies

# Read the full failure list
open build/reports/dependency-verification/dependency-verification-report.html

go deeper

for a junior

Know that a mismatch fails the build with an expected-vs-actual error, not a warning.

for a middle

Describe the report contents and the basic triage: did I change a version, or is the artifact different?

for a senior

Articulate the never-regenerate-blindly rule, the benign-vs-malicious distinction via publisher cross-check, and using --refresh-dependencies plus the HTML report.

for a principal

Define an incident-response posture: treat mismatches as security events, who investigates, escalation path, and policy that forbids silencing the check by regeneration.

## The failure mode Dependency verification is a hard gate. If any verified artifact's computed checksum doesn't match what's recorded, Gradle **fails the build before doing any work that depends on that artifact**. There's no 'warn and continue' for a mismatch — that would defeat the security purpose. The error is typically titled *"Dependency verification failed"* and lists, per artifact: - the component coordinates and file name, - the algorithm, - the **expected** checksum (from your metadata), - the **actual** checksum Gradle just computed, - the repository it came from. Gradle also writes an HTML report under `build/reports/dependency-verification/` summarizing every failure, which is easier to read than console output for large graphs. ## Why the gate matters The whole point is that a checksum mismatch is *exactly* the signal of either drift or an attack. The dangerous anti-pattern is to react to any failure by re-running `--write-verification-metadata` to 'make it pass'. That overwrites the trusted hash with whatever bytes you just received — if those bytes were malicious, you've now blessed them. **Never regenerate before you understand the cause.** ## Triage flow 1. **Did I change something?** If you bumped a version, added a dependency, or changed a repository, the metadata is stale and a mismatch/missing entry is expected. Regenerate deliberately and review the diff. 2. **Was the artifact re-published?** Repositories *should* be immutable, but occasionally a publisher re-uploads the same version with different bytes (rebuild, metadata fix). Confirm by fetching the artifact's checksum from the publisher's official channel (project site, Central UI). If it genuinely changed upstream and you trust it, update the metadata. 3. **Is something in the path tampering?** A corporate proxy, mirror, CDN, or a poisoned local cache could serve altered bytes. Clear and re-fetch: ```bash ./gradlew build --refresh-dependencies ``` If the mismatch persists from a clean fetch against the canonical repository, treat it as a potential compromise: do not regenerate, escalate, and compare the bytes against an independently trusted copy. ## Distinguishing benign vs malicious - **Benign drift** usually correlates with an action you took (version bump) or an announced upstream re-release; the new hash matches what the publisher advertises. - **Malicious tampering** shows bytes that differ from the *publisher's* advertised checksum, or only appear via a particular mirror/cache. Cross-checking the computed hash against the source of truth is the deciding test. ## Tooling that helps - The HTML report (`build/reports/dependency-verification/`) lists all failures at once. - `--refresh-dependencies` bypasses the cache to rule out cache poisoning. - Running the same build on a clean machine/CI runner isolates whether the problem is local. ## The principle A verification failure is a security event until proven otherwise. The correct senior reflex is *investigate the source of the mismatch*, not *silence the check*.

  • Why is reflexively re-running --write-verification-metadata after a mismatch dangerous?
    It overwrites the trusted hash with whatever bytes you just received. If those bytes were tampered with, you've laundered malicious content into 'verified'. Investigate the cause before regenerating.
  • How do you tell benign version drift from real tampering?
    Correlate with your own changes (version bump) and cross-check the computed hash against the publisher's official advertised checksum. If a clean re-fetch still disagrees with the source of truth, treat it as a compromise.
  • Where can you see all verification failures at once?
    Gradle writes an HTML report under build/reports/dependency-verification/, listing every failing artifact with expected and actual checksums.

A burglar alarm that mismatches: you don't re-arm it to whatever's now in the room — you first find out why it tripped.

saying these in an interview costs you the question

  • Saying you'd just regenerate the metadata to make the build pass.
  • Claiming Gradle warns and continues on a checksum mismatch.
  • Ignoring that a mismatch could be a supply-chain attack.

context

resolving links…