gradle --configuration-cache: Cache the Task Graph
gradle --configuration-cache stores the result of the configuration phase so subsequent builds reuse the task graph and start executing immediately.
Distinct from the build cache (which caches task outputs), the configuration cache caches the task graph itself. It is the biggest cold-start win once your build is compatible.
What it does
With --configuration-cache, Gradle serializes the configured task graph on the first run and reloads it on later runs with the same inputs, skipping the configuration phase. Build logic that reads the environment at execution time the wrong way (e.g. calling Project at execution) is reported as a problem.
Common usage
./gradlew build --configuration-cache
# enable by default
echo "org.gradle.configuration-cache=true" >> gradle.properties
# treat problems as warnings while migrating
./gradlew build --configuration-cache --configuration-cache-problems=warnFlags
| Flag / property | What it does |
|---|---|
| --configuration-cache | Enable the configuration cache |
| --no-configuration-cache | Disable it for this build |
| --configuration-cache-problems=warn|fail | Whether problems fail the build |
| org.gradle.configuration-cache=true | Enable by default |
In CI
The configuration cache entry is keyed on task inputs and environment; cache ~/.gradle/configuration-cache along with ~/.gradle/caches. Migrate incrementally with --configuration-cache-problems=warn, then flip to fail once clean.
Common errors in CI
"Configuration cache problems found in this build" lists each incompatibility, e.g. "invocation of 'Task.project' at execution time is unsupported". The fix is to capture values during configuration, not at execution. "Configuration cache entry discarded" means an input changed (a Gradle property or environment variable), which is expected, not an error.