Gradle dependency verification failed: what should you do?

When Gradle says dependency verification failed, read which kind of failure it is. Missing metadata is routine and means a new dependency needs an entry. A checksum mismatch, untrusted key or bad signature is more serious: check the artifact against the project's official sources before changing any file.

Four failure types

The failure message names the configuration, artifact, repository and what it expected. Start there.

Missing metadata

Gradle's documentation describes this as the simplest failure. It happens when you update a dependency and new versions, and possibly new transitive dependencies, come in. The message gives the missing group, artifact name and version, plus the entry to add. Regenerate with the write-verification-metadata command, read the diff, and commit it with the upgrade.

Untrusted signature

With signature verification on, Gradle verifies signatures but does not automatically trust them. A passing signature from a key not on your list still fails until you decide the key can be trusted and declare it. Treat this like adding a new reviewer to a code owners file: it is a decision, not a click.

Incorrect checksum

The documentation calls this the more serious case, and says the message shows the expected checksum from your metadata and the one actually computed. It indicates a dependency may have been compromised, and you must perform manual verification. It lists several scenarios:

1. The file was tampered with in the local cache. Delete it from the cache and Gradle downloads it again.
2. The dependency is available from multiple sources with slightly different binaries, such as differences in whitespace or timestamps.
3. A real change at the source.

Failed signature verification

Gradle says you must take action because this may indicate a compromised dependency. The options it describes: the signature was wrong in the first place, which happens frequently with dependencies published on different repositories, or the signature is right and the artifact has been compromised in the cache or remotely.

The documented approach is to go to the project's official site and see whether it publishes signatures. If it does, verify that the one Gradle downloaded matches. Only if you have confirmed the dependency is not compromised and just the signature is wrong, declare an artifact level key exclusion and provide a checksum.

What not to do

• Do not switch verification to off or lenient to get a green build. Lenient shows errors without failing, which hides them.
• Do not paste the new checksum from the error message without comparing it to an official source.
• Do not disable verification for a configuration unless you understand why, because Gradle warns whenever you do.

A quick triage routine

1. Is this a new dependency or version in the pull request? If yes and metadata is missing, regenerate and review.
2. If nothing changed on your side and a checksum fails, clear the cache and retry once.
3. If it still fails, treat it as an incident until you have compared with the official source.
4. Record what you found in the pull request so the next person knows.

New to this? Start with how to turn on Gradle dependency verification.

Safeguard dependency scanning adds the vulnerability view that verification does not provide, and its policy gates can hold a pull request while you investigate. Free scan: gold.safeguard.sh/scan.

Quick check

Sources

• Verifying Dependencies, Gradle documentation

Last reviewed: 19 October 2026.