Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Gradle says its dependency cache may be corrupt

ErrorGradle's dependency cache may be corrupt (this sometimes occurs after a network connection timeout.)

Short answer

Gradle trusted something in its local dependency cache that did not match the repository. First re-run the build with --refresh-dependencies so Gradle re-checks the repositories. If the cache is shared by parallel container builds, give each its own Gradle user home. If offline mode is on, turn it off.

  • Applies to Gradle 8.x and 9.x, Android Gradle plugin 8.x, Android Studio current stable
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the failing build once with the flag that tells Gradle to ignore its cached resolution results. If it passes, the cache was the problem; if not, read the first error under the warning.

    ./gradlew build --refresh-dependencies
  2. 2Match what you see, then jump to its fix

    1. 1The warning appears after a flaky connection, and the build passes on a different machineA cached entry is stale or was cut short by a timeoutFix
    2. 2Parallel CI jobs or containers mount the same Gradle user home, and the warning shows up at randomSeveral build processes share one cache and cannot talk to each otherFix
    3. 3The failure names a dependency you never built before, and --offline or Studio offline mode is activeOffline mode is on but a module is missing from the cacheFix

What does the error look like?

  • Gradle's dependency cache may be corrupt (this sometimes occurs after a network connection timeout.)

Cause 1 of 3

A cached entry is stale or was cut short by a timeout

1Check

Gradle keeps resolved modules and files under the user home, in a folder named modules-2 inside caches. Find where it is on this machine.

ls ~/.gradle/caches/

2Fix

Re-run with --refresh-dependencies. Gradle then ignores all cached entries for resolved modules and artifacts and asks the repositories again. It does only the work needed to refresh, not a full re-download of everything.

./gradlew build --refresh-dependencies

3Verify

The same task finishes without the cache warning.

./gradlew build

Confirmed by docs.gradle.org

Did this fix it?

Cause 2 of 3

Several build processes share one cache and cannot talk to each other

1Check

Gradle locks the cache with files. Sharing is safe only when the Gradle processes can communicate with each other, and that is usually not the case in containerized builds. Look for a shared mount.

echo "$GRADLE_USER_HOME"
docker inspect --format '{{ json .Mounts }}' my-ci-container

2Fix

Give every container its own Gradle user home with -g, so no two processes write to the same cache.

./gradlew build --gradle-user-home /tmp/gradle-home-job-1

3Verify

Run two jobs at the same time and watch for the warning.

./gradlew build --gradle-user-home /tmp/gradle-home-job-2

Confirmed by docs.gradle.org

Did this fix it?

Cause 3 of 3

Offline mode is on but a module is missing from the cache

1Check

In offline mode Gradle does not touch the network for dependency resolution. A module that is not already cached makes the build fail.

grep -rn "offline" gradle.properties ~/.gradle/gradle.properties; echo done

2Fix

Run the build once without --offline (and switch Studio offline mode off) so the missing module can be downloaded.

./gradlew build

3Verify

A later build with the cache filled passes, even offline.

./gradlew build --offline

Confirmed by docs.gradle.org

Did this fix it?

How do I stop it coming back?

  • Keep one Gradle user home per CI job or container instead of one mount shared by all of them.
  • Run a normal online build once on a new machine before you rely on --offline.
  • Retry the build after a network drop with --refresh-dependencies instead of editing cache folders by hand.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.