Troubleshoot Gradle Build Cache Issues – Diagnostic Guide

When Gradle’s build cache stops delivering speed, a systematic diagnostic approach can pinpoint the root cause. This guide walks through common cache symptoms, a concise cause/diagnostic table, ordered checks, targeted fixes, and when to seek help.

Problem Statement

Team members notice that builds that previously ran in seconds now take minutes. The console shows a low cache hit ratio (< 80%), or tasks that should be cached report Cache miss even though inputs haven’t changed. The goal is to determine why the build cache is ineffective and restore the performance gains.

Recognizable Symptoms

Console output: "Cache hit ratio: 0.78 (78%)" after a recent dependency update.
Gradle reports "Cache miss" for tasks that previously hit the cache.
Build fails with errors indicating corrupted cache entries.
Cache directory (~/.gradle/caches/build-cache-1) is full or missing files.
In a multi‑project build, some sub‑projects never hit the cache.

Cause / Diagnostic Table

Cause	Diagnostic Check
Inadequate task input declaration	Verify that tasks expose all inputs via `inputs.files` or `inputs.property`.
Cache corruption or stale entries	Run `gradle --scan` and inspect the "Build Cache" section for missing or corrupted entries.
Cache directory full or permission denied	Check size with `du -sh ~/.gradle/caches/build-cache-1` and file permissions.
Remote cache misconfiguration	Confirm `buildCache` settings in `gradle.properties` or `settings.gradle.kts` and test connectivity.
Gradle version mismatch (legacy vs new API)	Ensure project uses Gradle 7+ if relying on the new cache API; older projects may need `--build-cache` flag only.

Ordered Checks & Fixes

Confirm Cache Activation
Run the build with cache enabled:
```
gradle clean build --build-cache
```
Check the console for "Cache hit" or "Cache miss" lines. If no cache lines appear, the cache is disabled. Enable it in gradle.properties:
```
org.gradle.caching=true
```
Inspect Cache Hit Ratio
Execute gradle build --build-cache --scan and open the generated scan URL. In the "Build Cache" tab, look for the hit ratio. A ratio < 80% suggests issues. If the ratio is 100%, the problem may be elsewhere.
Validate Task Inputs
Identify tasks that report cache misses. For each, review its Gradle DSL for proper input declarations. Example for a custom Java compilation task:
```
tasks.register("compileCustom", JavaCompile) {
    source = fileTree("src/main/java")
    destinationDirectory = layout.buildDirectory.dir("classes")
    classpath = files()
    inputs.files source
    outputs.dir destinationDirectory
}
```
Missing inputs.files or inputs.property will cause Gradle to assume the task always needs to run.
Check Cache Directory Health
On the build machine, run:
```
du -sh ~/.gradle/caches/build-cache-1
find ~/.gradle/caches/build-cache-1 -type f -mtime +30 -print
```
If the directory is > 10 GB or contains many stale files, consider pruning:
```
gradle cleanBuildCache
```
Note: cleanBuildCache removes only the local cache, preserving remote entries.

Examine Permissions

Ensure the user running Gradle owns the cache directory and has read/write permissions. On Linux:

ls -ld ~/.gradle/caches/build-cache-1
chown -R $(whoami):$(whoami) ~/.gradle/caches/build-cache-1
chmod -R u+rw ~/.gradle/caches/build-cache-1

Verify Remote Cache Configuration (CI)
In CI environments, remote cache is often used. Check settings.gradle.kts for a block like:
```
buildCache {
    local { isEnabled = false }
    remote(HttpBuildCache::class) {
        url = uri("https://cache.example.com/gradle")
        push = true
    }
}
```
Run a build with --build-cache and inspect the console for messages like "Uploading cache entry" or "Fetching from remote cache". If no communication occurs, verify network access and credentials.
Test with a Minimal Build
Create a new Gradle project with a simple task that should be cached (e.g., a copy task). Run it multiple times with cache enabled. If the minimal build works, the issue lies in the original project’s configuration. If it fails, the problem may be global (cache corruption, permissions, or network).
Apply Fixes Based on Findings
- For missing inputs: add the necessary inputs declarations.
- For corrupted entries: clear the cache with gradle cleanBuildCache and rebuild.
- For size/perms: prune stale files or adjust maxCacheSize settings.
- For remote misconfig: correct the URL, credentials, or enable the remote cache flag.
Re‑run and Verify
After applying fixes, run gradle build --build-cache --scan again. The scan should show a hit ratio ≥ 80% and no cache miss messages for previously problematic tasks.

Escalation Criteria

If after all checks the hit ratio remains < 80% and tasks still miss, consider the possibility of a Gradle bug. Search the Gradle issue tracker for similar reports and file a new issue with the build scan link.
In multi‑project builds, if only certain sub‑projects miss the cache, isolate the problem by building each sub‑project individually to determine if the issue is local to that module.
When using the new Gradle 7+ cache API, ensure no legacy --build-cache flags conflict with buildCache { local { ... } } blocks.
For CI environments, if remote cache connectivity fails, check the CI runner’s network policies and any proxy settings that might block HTTP/HTTPS traffic.

Practical Verification Checklist

Run gradle --version to confirm Gradle 7+ is in use.
Check gradle.properties for org.gradle.caching=true.
Run gradle build --build-cache --scan and open the scan URL.
Verify the cache directory size with du -sh ~/.gradle/caches/build-cache-1.
Ensure the user has ownership and read/write permissions on the cache directory.
Confirm remote cache URL and credentials in settings.gradle.kts or gradle.properties.

Takeaway

Gradle’s build cache is a powerful performance lever, but its effectiveness hinges on correct configuration and healthy cache storage. By following the ordered checks above—verifying activation, inspecting hit ratios, validating task inputs, ensuring directory health, and confirming remote connectivity—you can quickly isolate the root cause of cache failures and apply the appropriate fix. Regularly monitor cache statistics with Gradle scans to catch regressions early and keep build times in check.

Diagnosing and Fixing Gradle Build Cache Problems: A Step‑by‑Step Guide