---
title: "Gradle Configuration Cache Internals: Cut CI Build Times in Half"
published: true
description: "Deep dive into Gradle's configuration cache — task graph serialization, cache miss root causes, incompatible plugins, and a systematic migration strategy for Android and KMP projects."
tags: kotlin, android, architecture, mobile
canonical_url: https://mvpfactory.co/blog/gradle-configuration-cache-internals
---
What We Are Building
By the end of this workshop, you will understand exactly how Gradle's configuration cache serializes the task graph to disk, why cache misses happen, and how to run a systematic migration on a multi-module Android or KMP project. In real-world 50+ module projects, this can cut CI build times by 40–60%.
Prerequisites: Familiarity with Gradle build scripts in Kotlin DSL, a multi-module Android or KMP project, and AGP 8.x / KGP 1.9+.
The Mental Model First
The configuration cache is not the build cache. Here is the distinction you need to burn in:
- Build cache — stores task outputs
- Configuration cache — stores the task graph
Gradle's build lifecycle has three phases:
- Initialization — which projects participate
-
Configuration — evaluate every
build.gradle.kts, construct the task DAG - Execution — run tasks
Configuration is the expensive part. In a 50-module Android project, evaluating every script can consume 15–30 seconds on every single CI run. The configuration cache serializes the resolved task graph to .gradle/configuration-cache/ as a binary snapshot. On subsequent runs where inputs have not changed, Gradle replays the snapshot and skips configuration entirely.
Why Cache Misses Happen: Three Root Causes
1. Undeclared Inputs
Here is the gotcha that will save you hours. If your build script reads an environment variable without declaring it as an input, Gradle cannot track it — and any change invalidates the entire cache.
// BAD — undeclared input, causes a cache miss on every CI run
val version = System.getenv("BUILD_NUMBER")
// GOOD — declared as a provider, properly tracked
val version = providers.environmentVariable("BUILD_NUMBER")
2. File System Reads at Configuration Time
Reading files during configuration rather than execution is a classic footgun. Gradle cannot fingerprint what it does not know about.
// BAD — reads file at configuration time
val props = File("local.properties").readText()
// GOOD — deferred to execution via ValueSource
abstract class LocalPropertiesSource : ValueSource<String, ValueSourceParameters.None> {
override fun obtain(): String = File("local.properties").readText()
}
val props = providers.of(LocalPropertiesSource::class) {}
3. Incompatible Plugins
This is where most migrations stall. Third-party plugins that hold Project references at execution time, mutate shared state, or use deprecated APIs will fail cache compatibility checks.
| Plugin category | Typical compatibility | Common fix |
|---|---|---|
| AGP 8.x+ | Full | Upgrade to 8.x |
| KGP 1.9+ | Full | Upgrade to 1.9+ |
| Custom in-house plugins | Variable | Refactor to Provider APIs |
| Legacy annotation processors | Often incompatible | Migrate to KSP |
| Some publishing plugins | Partial | Pin version, file upstream issue |
Step-by-Step Migration
Let me show you a pattern I use in every project: incremental migration. Never flip the flag project-wide. I have watched teams do that and spend weeks untangling the fallout.
Phase 1 — Establish a Baseline With --warn
./gradlew assembleDebug --configuration-cache --configuration-cache-problems=warn
This runs with the cache enabled but treats problems as warnings, not failures. You get an HTML report at build/reports/configuration-cache/. Open it. Every problem has a stack trace pointing to the exact line.
Phase 2 — Fix By Category
Work through problems in this order: your code first, then plugins. Problems in your own build scripts are cheap to fix. Waiting on upstream plugin fixes can take months.
// Replace direct Task references with lazy providers
// BAD
tasks.named("generateBuildConfig").get().outputs.files
// GOOD
tasks.named("generateBuildConfig").flatMap { it.outputs.files.elements }
Phase 3 — Fingerprinting Debug for Persistent Misses
If the cache keeps missing after your fixes, use verbose fingerprinting:
./gradlew assembleDebug --configuration-cache \
-Dorg.gradle.configuration-cache.internal.report-file-system-access=true
The docs do not mention this prominently, but this flag surfaces every file access during configuration — giving you a precise list of violations the standard report missed.
Phase 4 — Lock It in CI
# .github/workflows/build.yml
- name: Build
run: ./gradlew assembleDebug --configuration-cache
env:
GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
Treat any configuration cache failure as a build failure. This prevents regressions from slipping in silently.
Real Build Time Numbers
These come from profiling real multi-module Android projects — treat them as rough benchmarks:
| Project size | Config phase (before) | Config phase (after) | Total CI improvement |
|---|---|---|---|
| 20 modules | ~12s | ~1s | ~18% |
| 50 modules | ~28s | ~2s | ~35% |
| 100+ modules | ~60s+ | ~3s | ~50%+ |
Gains compound when you combine this with the remote build cache (Develocity or GitHub Actions cache). The configuration cache eliminates the fixed cost per run; the build cache eliminates the incremental cost.
Gotchas
-
providers.environmentVariableis not optional —System.getenv()looks harmless but breaks cache tracking completely - AGP and KGP versions matter — both need to be at their minimum compatible versions before you start. Trying to migrate on AGP 7.x is a dead end
-
Your internal plugins are the unsung blocker — most teams focus on third-party plugins, but custom in-house Gradle plugins with raw
Projectreferences will silently cause misses - Cache invalidation is all-or-nothing — a single incompatible input invalidates the entire graph, so fix your build scripts before worrying about plugins
Conclusion
Here is the minimal setup to get this working today:
- Run
--configuration-cache-problems=warnwithout changing any code. Triage the HTML report for one sprint - Migrate your internal plugins first — replace
Projectreferences withProvider-based APIs - Enforce it in CI as a hard failure once the initial migration is clear
The configuration cache is one of the highest-leverage performance changes available to Android and KMP teams. The mental model is straightforward once you understand what it actually serializes. The migration is mechanical once you know the three root causes.
Further reading:
Top comments (0)