skip to content

Once verification-metadata.xml exists, what causes a Gradle build to fail verification, and how does Gradle present the failures?

level: middleimportance: should knowfreq 35%

answer

  1. mismatch / bad signature / no entry
  2. deny-by-default once file exists
  3. HTML report under build/reports/dependency-verification
  4. --dependency-verification lenient | off
  5. fix = review then update metadata

basics

~20 s

The build fails if a downloaded artifact's recomputed checksum/signature doesn't match the recorded value, or if an artifact has no entry at all (and no trust rule). Gradle reports each failing artifact and writes an HTML report you can open.

solid answer

~50 s

With the file present, verification is strict by default: every artifact Gradle resolves must either match a recorded checksum/signature in `<components>` or be covered by a `<trusted-artifacts>`/`<trusted-keys>` rule. A build **fails** when (1) a recomputed hash differs from the `<sha256>`/`<sha512>` value (tampering or a re-published artifact), (2) `verify-signatures` is on and the signature is missing/invalid/signed by an untrusted key, or (3) an artifact is resolved that has **no matching entry** at all — a new or transitive dependency you haven't pinned yet. Gradle aggregates all problems for the resolution and prints them, then writes a human-readable report to `build/reports/dependency-verification/verification-report.html` listing each artifact, the expected vs actual value, and the reason. You can soften the policy per-invocation with `--dependency-verification lenient` (log warnings, continue) or `off`; the durable fix is to regenerate/update the metadata after reviewing the change.

code

bash · 8 lines
bash
# Inspect what failed without blocking the build:
./gradlew build --dependency-verification lenient

# Open the detailed report:
open build/reports/dependency-verification/verification-report.html

# Skip verification entirely (debugging only):
./gradlew build --dependency-verification off

go deeper

for a junior

Know that a checksum mismatch or an unlisted artifact fails the build.

for a middle

List the three failure causes and know where the HTML report is and the lenient/off overrides.

for a senior

Explain why missing-entry failures are desirable friction and the safe remediation flow (review then update, never blindly turn off).

for a principal

Set policy that off/lenient are forbidden in CI, that report review is mandatory, and how upgrades are gated by verification updates.

## Strict by default The presence of `gradle/verification-metadata.xml` enables *deny-by-default* verification. Every artifact resolved during the build is checked, and the build aborts on the first resolution that contains an unverifiable artifact (Gradle collects all problems in that resolution before failing, so you usually see several at once). ## The three failure causes 1. **Checksum mismatch.** Gradle recomputes the configured algorithm on the downloaded bytes and compares to the recorded `value`. A difference means the bytes changed — could be tampering, a CDN re-publish, or a wrong/edited entry. 2. **Signature problems** (only when `<verify-signatures>true`). The artifact's `.asc` is missing, malformed, fails validation, or is signed by a key not present in `<trusted-keys>` / the artifact's `<pgp>` entry. 3. **Missing entry.** An artifact with *no* matching `<artifact>` element and not covered by any trust rule. This is the most common day-to-day failure: you added or upgraded a dependency (or a transitive one changed) and haven't pinned it yet. ## How failures are presented Gradle prints a console error naming the offending artifacts, and — importantly — writes a detailed report: ``` build/reports/dependency-verification/verification-report.html ``` The report lists, per artifact: the coordinates, the file, the expected value, the actual computed value, and the failure category. Reviewing it is the right first step before changing anything. ## Per-invocation overrides You don't have to delete the file to get past a failure temporarily: ```bash # Warn instead of fail (still logs problems): ./gradlew build --dependency-verification lenient # Skip verification entirely for this run: ./gradlew build --dependency-verification off ``` These are escape hatches for debugging — not a fix. The durable resolution is to inspect the change (is the new checksum legitimate?) and update the metadata accordingly, committing the reviewed change. ## Why a missing-entry failure is a feature, not a bug It forces a human decision every time the set of trusted bytes changes: a new dependency, an upgrade, or an unexpected transitive shift can't silently enter the build. That deliberate friction is the integrity guarantee in action.

  • Where does Gradle write the detailed verification failure report?
    To build/reports/dependency-verification/verification-report.html, listing each failing artifact with expected vs actual values and the failure reason.
  • A new transitive dependency appeared and the build now fails verification. Is that a bug?
    No — it's the intended behaviour. The new artifact has no trusted entry, so verification correctly stops it until a human reviews and pins it.

saying these in an interview costs you the question

  • Recommending --dependency-verification off as the fix rather than a temporary debugging step.
  • Treating a missing-entry failure as a Gradle bug instead of the intended deny-by-default behaviour.

context

resolving links…