gradle --build-cache: Usage & Common CI Errors
Reuse task outputs across builds and machines to skip redundant work.
--build-cache enables the Gradle build cache for a build, allowing cacheable tasks to reuse outputs from a previous build (or another machine via a remote cache) instead of re-executing. It is one of the biggest CI speedups available to Gradle projects.
What it does
When enabled, Gradle computes a cache key from each task’s inputs and, on a hit, copies the stored outputs instead of running the task. It can be turned on per-invocation with the flag or permanently with org.gradle.caching=true in gradle.properties, and backed by a shared remote cache.
Common usage
./gradlew build --build-cache
# gradle.properties (persistent):
org.gradle.caching=trueCommon error in CI (and the fix)
Symptom: the build cache never hits in CI even though the code is unchanged. Cause: unstable task inputs (absolute paths, timestamps, environment-specific values) change the cache key on every run. Fix: enable --scan to inspect why a task was not cached, normalize inputs (avoid absolute paths and volatile env), and ensure the remote cache is reachable and the same Gradle version is used across runs.