skip to content

When you enable the configuration cache and a build reports problems, Gradle prints a link to a configuration-cache-report.html file. What is in that report and how do you use it?

level: juniorimportance: must knowfreq 55%

answer

  1. self-contained HTML under build/reports/configuration-cache
  2. problems grouped by category
  3. ownership/location tree to the call site
  4. console only prints summary + link
  5. de-duplicated with counts

basics

~20 s

It is an HTML report Gradle generates listing every configuration-cache problem found, grouped by category, with the task or input that caused each one and a stack-trace-like location so you can find and fix the offending code.

solid answer

~40 s

The `configuration-cache-report.html` is a standalone, self-contained HTML file Gradle writes (under `build/reports/configuration-cache/...`) whenever the configuration cache encounters problems. It lists each problem with a human-readable message, a category (e.g. unsupported type, reading a system property at configuration time, project access at execution time), and a navigable tree showing the ownership chain — which task, input, or build-logic location triggered it. You open it in a browser, expand a problem, and it points you at the exact API call or task to fix. The console only prints a short summary plus the file link, so the HTML is where you actually diagnose. It also de-duplicates: identical problems are grouped with a count rather than repeated.

code

bash · 5 lines
bash
$ ./gradlew build --configuration-cache
> Configuration cache problems found in this build.
  3 problems were found storing the configuration cache.
  See the complete report at
  file:///proj/app/build/reports/configuration-cache/abc123/def456/configuration-cache-report.html

go deeper

for a junior

Know it's an HTML report listing configuration-cache problems with categories and locations, and that you open it in a browser to find what to fix.

for a middle

Explain the ownership/location tree, de-duplication, that the console only summarizes, and roughly where the file lives.

for a senior

Tie it to the config/execution phase split and configuration inputs; describe a real triage workflow from report to fix.

for a principal

Discuss using the report as a gate in CI, tracking problem counts over time, and driving plugin owners to fix categories at scale.

## What the configuration cache is (briefly) Gradle splits a build into a **configuration phase** (it evaluates build scripts, registers tasks, wires inputs/outputs) and an **execution phase** (it runs the tasks). The **configuration cache** stores the result of the configuration phase — the serialized task graph and its state — so that on the next compatible invocation Gradle can skip configuration entirely and jump straight to execution. This is a big speedup, but it only works if your build logic obeys certain rules (no reading mutable global state at execution time, no holding `Project` references during execution, only serializable state, etc.). ## The problems report When Gradle stores or loads the cache and detects code that breaks those rules, it records a **problem**. Rather than dumping everything to the console, it writes a single, self-contained `configuration-cache-report.html` (typically under `build/reports/configuration-cache/<hash>/<hash>/configuration-cache-report.html`). The console shows only a summary like `N problems were found ... See the complete report at file://...`. The HTML report contains: - **A list of problems**, each with a clear message such as *“invocation of 'Task.project' at execution time is unsupported”* or *“cannot serialize object of type ...”*. - **A category** for each problem so you can triage by kind. - **An ownership / location tree**: expanding a problem shows the chain — build → task `:app:foo` → input → the specific call site — so you can navigate from symptom to the exact line of build logic. - **De-duplication**: the same problem hit many times is grouped with a count, keeping the report readable. - **Input-tracking info**: it also surfaces *configuration inputs* (files, env vars, system properties read at configuration time) that affect cache validity. ## How you use it 1. Run with the configuration cache enabled. 2. If problems are reported, open the linked HTML in a browser. 3. Expand a problem, read its category and message, follow the ownership tree to the offending task/plugin. 4. Fix the build logic (use a `Provider`, a `BuildService`, inject services, etc.) or, as a stopgap, mark the task incompatible. 5. Re-run and confirm the count drops. The report is the primary diagnostic surface — the console is intentionally terse.

  • Why does Gradle write an HTML file instead of just printing all the problems to the console?
    Reports can contain dozens of problems with deep location chains; an interactive, de-duplicated HTML tree is far more navigable than a wall of console text, and it keeps the console output short while preserving full detail on disk.
  • Where does the report live and is it overwritten?
    Under build/reports/configuration-cache/ in a hash-named subdirectory keyed to the build; each distinct build invocation/cache entry gets its own path, so different builds don't clobber each other's reports.

saying these in an interview costs you the question

  • Claiming the report lists build-cache (task output) misses rather than configuration-cache problems — they are different caches.
  • Saying the console shows all problems — it only shows a summary and the link.

context

resolving links…