DEV Community

SoftwareDevs mvpfactory.io
SoftwareDevs mvpfactory.io

Posted on Originally published at mvpfactory.io

Gradle Configuration Cache Internals

---
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
---
Enter fullscreen mode Exit fullscreen mode

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:

  1. Initialization — which projects participate
  2. Configuration — evaluate every build.gradle.kts, construct the task DAG
  3. 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")
Enter fullscreen mode Exit fullscreen mode

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) {}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 }
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.environmentVariable is 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 Project references 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:

  1. Run --configuration-cache-problems=warn without changing any code. Triage the HTML report for one sprint
  2. Migrate your internal plugins first — replace Project references with Provider-based APIs
  3. 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)