skip to content

A build fails with a signature verification error after adding or bumping a dependency. How do you diagnose and resolve it without weakening security?

level: seniorimportance: should knowfreq 38%

answer

  1. read build/reports/dependency-verification report
  2. classify: untrusted key / no sig / unfetchable / bad sig
  3. regenerate + --export-keys, then verify fingerprint
  4. never disable verify-signatures to go green
  5. bad signature = investigate, not suppress

basics

~20 s

Read the report at build/reports/dependency-verification/, identify whether the key is untrusted, missing, or the signature is genuinely bad. Re-run --write-verification-metadata pgp,sha256 --export-keys to add legitimate new keys after verifying the fingerprint; never just delete verification or blanket-trust.

solid answer

~50 s

First read the **HTML report** Gradle writes under `build/reports/dependency-verification/` (and the console message) — it names the failing artifact and the cause. Common causes after a bump: (1) the new artifact is signed by a **key not yet in your trusted set** — legitimate, fix by re-running `--write-verification-metadata pgp,sha256 --export-keys`, then *verify the new fingerprint against the publisher* before committing; (2) **no signature published**, so it fell to checksum and the recorded checksum is stale — regenerate the checksum; (3) the **public key couldn't be fetched** (key-server outage / disabled servers without keyring entry) — add it to the keyring; (4) a **genuinely invalid signature** — that's a real red flag, do not paper over it. The cardinal rule: never resolve a failure by disabling `verify-signatures`, blanket-trusting all keys, or adding the artifact to `<trusted-artifacts>` without understanding why — those discard the protection. Each fix should be a reviewed diff to the metadata/keyring.

code

bash · 6 lines
bash
# Inspect the failure
open build/reports/dependency-verification/verification-report.html

# Legit new key after a bump: regenerate + export, THEN review the diff
./gradlew --write-verification-metadata pgp,sha256 --export-keys help
git diff gradle/verification-metadata.xml gradle/verification-keyring.keys

go deeper

for a junior

Know to look at the verification report and regenerate metadata rather than guessing.

for a middle

Classify the failure type and apply the matching regeneration/export fix.

for a senior

Distinguish legitimate vs suspicious failures, avoid the security anti-patterns, and insist on fingerprint review.

for a principal

Define incident response and PR-review policy for verification failures so 'make it green' never bypasses authenticity across the org.

## Step 1 — read the report When verification fails, Gradle fails the build **before** using the artifact and writes a detailed report: ``` build/reports/dependency-verification/verification-report.html ``` The console error also names the artifact and a reason. Categorize the cause before touching anything. ## The common causes and the *correct* fix for each ### 1. New, untrusted key (most common after a bump) The bumped artifact is signed by a key you haven't trusted yet. This is legitimate and expected. Fix: ```bash ./gradlew --write-verification-metadata pgp,sha256 --export-keys help ``` Then **verify the new fingerprint** out-of-band (publisher's website, prior known fingerprint) and review the metadata/keyring diff in the PR before committing. The danger is rubber-stamping: re-generating silently adds whatever key signed the artifact, so a human must confirm it's the real publisher. ### 2. Stale checksum on an unsigned artifact If the artifact has no `.asc`, verification fell back to checksum, and a re-published or changed artifact now mismatches. Regenerate the checksum (same write command). Investigate *why* it changed — a checksum changing for a fixed coordinate is itself suspicious. ### 3. Public key cannot be fetched If you disabled `<key-servers>` but the key isn't in your keyring, or the key server is down, Gradle can't get the public key. Fix by exporting the key into the keyring (`--export-keys`) rather than re-enabling flaky servers. ### 4. Genuinely invalid signature The signature doesn't validate against the trusted key. This is a real integrity/authenticity failure — treat it as a potential compromise. Do **not** suppress it; investigate the source repository/mirror. ## Anti-patterns (what NOT to do) - `verify-signatures=false` or deleting `verification-metadata.xml` — throws away all protection. - Adding a global unscoped `<trusted-key>` for *every* failing key without checking fingerprints. - Dumping the artifact into `<trusted-artifacts>` (skip-verification escape hatch) just to make the build green. - Using `--refresh-keys` or regeneration blindly without reviewing the resulting diff. ## Useful flags while debugging - `--write-verification-metadata sha256,pgp` regeneration to refresh entries. - `--export-keys` to populate the keyring. - `--dry-run`-style resolution via a lightweight task (`help`) to resolve without running heavy tasks. - Inspect `gradle/verification-keyring.keys` to see which keys are present. ## The principle Every resolution should *preserve* the property that consumed artifacts are authentic. Legitimate failures get a reviewed metadata/keyring update with a validated fingerprint; suspicious failures get investigated, not silenced. The verification feature is only as strong as the discipline applied when it fails.

  • Where does Gradle put the detailed verification failure report?
    Under `build/reports/dependency-verification/` (an HTML report naming each failing artifact and the reason), in addition to the console error.
  • Why is dropping a failing artifact into <trusted-artifacts> a bad fix?
    <trusted-artifacts> skips verification entirely for that artifact, so you lose both integrity and authenticity checks just to make the build green — masking the real cause.
  • After regenerating to add a new key, what must a reviewer still do?
    Cross-check the new fingerprint against the publisher out-of-band before approving the diff; regeneration trusts whatever signed the artifact, so the human review is the actual security control.

saying these in an interview costs you the question

  • Setting verify-signatures=false or deleting the metadata to make the build pass.
  • Blanket-trusting every failing key without checking fingerprints.
  • Ignoring a genuinely-invalid signature instead of investigating a possible compromise.

context

resolving links…