Configuration Cache

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.

Gradle serializes the resolved task graph — the tasks to run plus their configured state — to disk. On a cache hit it loads that snapshot and skips the whole configuration phase, going straight to executing tasks.

requested means the user asked for the configuration cache; active means it is actually operating. They diverge when, for example, the user sets it in gradle.properties but passes --no-configuration-cache on the command line — requested true, active false.

BuildFeatures is a Gradle service exposing whether opt-in features like the configuration cache are requested and active. A plugin gets it via gradle.serviceOf<BuildFeatures>() (or constructor injection) and reads configurationCache.requested / .active.

Call gradle.sharedServices.registerIfAbsent("name", MyService::class) { parameters { ... } }. It returns a Provider<MyService>. registerIfAbsent is idempotent, so registering the same name twice (e.g. from two plugins) reuses one instance instead of failing.

The configuration cache serializes the task graph and reuses it, so plain shared objects or statics aren't re-created or shared correctly across tasks and parallel workers. A BuildService is the supported holder for shared state that the config cache understands and reuses safely.

By default configuration-cache problems fail the build; setting org.gradle.configuration-cache.problems=warn downgrades them to warnings so the build proceeds. It's a transitional setting used while migrating an incompatible build.

The configuration cache stores the task graph and reuses it without re-running configuration. Tasks must not touch the live Project at execution time; doing so triggers a configuration-cache problem because Project cannot be serialized into the cached graph.

System.getenv() reads ambient state Gradle can't track, so a cache hit could reuse a stale value. Use providers.environmentVariable("NAME"), which records the variable as a build input and invalidates the cache when it changes.

It controls what Gradle does when configuration-cache problems are found. fail (the default) fails the build after reporting them; warn reports them but lets the build continue. Use warn during migration to keep working, fail once you're clean to prevent regressions.

The key includes the set of requested tasks, plus the values of any system properties, environment variables, Gradle properties, and files read during configuration. Change any of these and the entry is invalidated, so Gradle recomputes the graph.

Enabling it lets Gradle skip the configuration phase on repeat runs by reusing a cached task graph, so builds start executing tasks faster — especially noticeable on large multi-project builds.

'Reusing configuration cache.' means Gradle found a valid cached task graph and skipped the configuration phase. On the first run there is no entry, so it instead reports that it is calculating/storing the task graph.

The closure runs at execution time but holds a reference to the non-serializable Project, so the cache reports a problem. Capture the value you need into a local val (or task property) during configuration, then reference that local inside doLast.

Common categories: reading a non-serializable value into cached state, accessing the Project (or task.project) at execution time, reading system properties / env vars / files at configuration time, and using unsupported types. Each category points at a different rule the build logic broke.

Because the configured task state must be serializable. Capturing values lazily through Provider/Property and declared task inputs lets Gradle store and restore them. Capturing a Project or other live objects in a closure makes the graph unserializable.

Query buildFeatures.configurationCache.active. If false, take the legacy/incompatible path; if true, take the cache-safe path. This lets older plugins keep working with the cache on without crashing.

STABLE_CONFIGURATION_CACHE is a Gradle feature preview that turns on the stricter configuration-cache checks even without the cache active. Enabling it early surfaces incompatibilities so you can fix them before committing to the cache.

Gradle creates exactly one instance per build, lazily, and closes it (if AutoCloseable) when the build ends. It does NOT synchronize your methods, so any mutable internal state must be made thread-safe by you. maxParallelUsages can throttle concurrent users.

Expose an abstract Property<MyService> on the task and either set it from the provider plus call usesService(provider), or annotate it with @ServiceReference("name") so Gradle auto-wires and registers the usage. @ServiceReference removes the manual wiring boilerplate.

Command-line flags override gradle.properties for that run. Properties resolve from project gradle.properties, then ~/.gradle/gradle.properties, then -D/-P overrides. Control per-environment by setting the flag in CI scripts and the property (or its override) locally.

Inject ProjectLayout (replaces project.file/buildDir), ExecOperations (replaces project.exec), FileSystemOperations (replaces project.copy/delete), ObjectFactory, and ProviderFactory. Obtain them via constructor @Inject (or an abstract @get:Inject getter) — never reference Project.

A ValueSource wraps a read of external state (like a git command's output) so its result is tracked as a build input. You use it when no built-in provider (environmentVariable, systemProperty, fileContents) covers the source.

Start in warn mode so builds keep working, use the HTML report to triage problems by category, fix or mark tasks incompatible, drive the count down, then flip CI to fail mode to lock in the clean state and catch any new regressions.

It marks a specific task as incompatible with the configuration cache, telling Gradle to skip reusing the cached config when that task runs (and not report it as a hard failure). It's a stopgap for tasks you can't fix yet; the downside is you lose cache benefit for any build including that task.

Run twice with the identical command. If the store run reports configuration cache problems (e.g. unserializable state), it can't be reused — fix those. If there are no problems but it still misses, a tracked input (a property, env var, or file) is changing between runs.

On a miss, Gradle runs configuration, serializes the task graph to an entry keyed by the build inputs, then executes. On a hit, it finds an entry whose key matches the current inputs, deserializes the graph, and executes without re-running configuration.

Move the static state into an abstract BuildService<Params>, pass any needed config (paths, flags) via Params instead of capturing Project, register it with registerIfAbsent, and have each task reference it via @ServiceReference. Remove statics and execution-time Project access.

BuildFeatures also exposes isolatedProjects, with the same requested/active Provider<Boolean> pair. You introspect it the same way: gradle.serviceOf<BuildFeatures>().isolatedProjects.active.getOrElse(false).