Configuration Cache Requirements for your Build Logic

Some types must not be referenced by task fields or in task actions (methods annotated @TaskAction, or the doFirst {} and doLast {} DSL blocks).

These types fall into the following categories:

These restrictions exist because these types cannot easily be stored or reconstructed by the Configuration Cache.

The Configuration Cache serializes a fixed set of standard collection, set, map, and queue implementations directly:

These types, and Guava’s immutable collections (ImmutableList, ImmutableSet, ImmutableMap), are stored and restored faithfully.

A custom subtype of one of the standard types above (for example, class MyList extends ArrayList<String> {}) cannot be restored as its own type: it is restored as the nearest standard type instead. Any state or behavior added by the custom type — extra fields, overridden methods — is lost.

Referencing a custom collection or map subtype from task fields or task actions is deprecated and will become an error in Gradle 10. Use a standard collection type (for example, a plain ArrayList or LinkedHashMap) and hold any extra data in separate, explicitly serialized fields.

Tasks must not use any Project objects during execution. This includes calling Task.getProject() while a task is running.

Some cases can be resolved similarly to those described in disallowed types.

Often, equivalent functionality is available on both Project and Task. For example:

The following task incorrectly references the Project object at execution time:

Fixed version:

If the same problem occurs in an ad-hoc task in a script:

Fixed version:

Fixing ad-hoc tasks in scripts requires additional effort, making it a good opportunity to refactor them into proper task classes.

The table below lists recommended replacements for commonly used Project methods:

When using ad-hoc tasks in build scripts, task actions (such as doLast {}) can inadvertently capture references to the enclosing build script scope. The Configuration Cache must serialize these captured references, and project-level objects are not serializable.

Tasks must not directly access the state of another task instance. Instead, they should be connected using input and output relationships.

This requirement ensures that tasks remain isolated and correctly cacheable. As a result, it is unsupported to write tasks that configure other tasks at execution time.

The pre-Configuration Cache pattern reaches directly into another task’s properties from within a task action. Here processData reads the output of generateData by holding a reference to the task and dereferencing it at execution time:

Under the Configuration Cache, this fails serialization: a task cannot hold a TaskProvider referring to another task, whether directly as a field or indirectly through a closure capture in a doLast. To consume another task’s output, the reference must be either wrapped in a ConfigurableFileCollection (so it flows through as file inputs), or transformed with .map { …​ } / .flatMap { …​ } into a serializable value (typically a Provider of the file itself).

The Configuration Cache-compatible version declares the source file as an @InputFile on the consuming task and wires the two tasks together with flatMap. Gradle infers the task dependency automatically from the property wiring:

When storing a task in the Configuration Cache, all objects referenced through the task’s fields are serialized.

In most cases, deserialization preserves reference equality—if two fields a and b reference the same instance at configuration time, they will still reference the same instance after deserialization (a == b, or a === b in Groovy/Kotlin syntax).

However, for performance reasons, certain classes—such as java.lang.String, java.io.File, and many java.util.Collection implementations—are serialized without preserving reference equality. After deserialization, fields that referred to these objects may reference different but equal instances.

Consider a task that stores a user-defined object and an ArrayList as task fields:

Without Configuration Cache, reference equality is preserved in both cases:

With Configuration Cache enabled, only user-defined object references remain identical. List references are different, although the lists themselves remain equal:

Best Practices:

Reference equality is never preserved between tasks—each task is an isolated "realm." To share objects across tasks, use a Build Service to wrap the shared state.

Tasks must not access conventions, extensions, or extra properties at execution time.

Instead, any value relevant to task execution should be explicitly modeled as a task property to ensure proper caching and reproducibility.

A common pre-Configuration Cache pattern stores configuration values on a task’s ExtraPropertiesExtension (the ext block) and reads them from within a task action. Here a release task reads a banner from ext.banner:

Under the Configuration Cache, reading extra["banner"] (or ext.banner) from inside the task action is unsupported, because extension storage isn’t part of the captured task state.

The Configuration Cache-compatible version exposes the value as a typed @Input property on a proper task class:

Plugins and build scripts must not register build listeners that are created at configuration time and triggered at execution time. This includes listeners such as BuildListener, TaskExecutionListener, and the gradle.taskGraph.afterTask and gradle.buildFinished callbacks. These callbacks run as part of the configuration phase, so they don’t fire when the configuration phase is skipped on a cache hit.

The Configuration Cache provides supported replacements for the two most common patterns: observing task execution events, and running logic at the end of the build.

Build Services are the Gradle-supported way to share state across tasks, replace BuildListener-style hooks, and observe task execution events. They are also the most common feature-level integration point with the Configuration Cache, and a few caveats apply.

Parameter values are part of the cache entry. The parameters interface of a build service is a custom Gradle type, and its property values are serialized into the Configuration Cache entry alongside the rest of the build’s configured state. Parameter property types must be Configuration Cache-compatible. Standard managed property types (Property<T>, RegularFileProperty, ListProperty<T>, and so on) are supported containers, but the value type T must also be serializable by the Configuration Cache. For example, Property<String> is safe, but Property<Thread> is not. Raw Configuration references, live JVM state, and Project references are not supported as parameter values.

The service lifecycle differs under the Configuration Cache. Only the parameters are cached — service instances are not. With the Configuration Cache enabled, build services follow this lifecycle:

A BuildServiceProvider cannot drive a ValueSource at configuration time. Passing a provider of a BuildService (or anything derived from it via map or flatMap) as a ValueSourceParameters value that is read at configuration time is not supported.

If you do not need the service-derived value at configuration time, use @ServiceReference for direct injection or store the build service reference in an @Internal-annotated property on a task instead.

Sometimes you may want to use a BuildService to derive a parameter for a ValueSource, like this:

This is only supported by the Configuration Cache if the resulting ValueSource isn’t used at configuration time. If you need the ValueSource’s value at configuration time, you have to tell the Configuration Cache to use the computed input value for fingerprinting by wrapping the eager computation in a `provider {} block:

See the related not-yet-implemented entry for the current state.

Register as OperationCompletionListener to observe task execution. A build service that implements OperationCompletionListener and is registered via BuildEventsListenerRegistry.onTaskCompletion is the supported way to observe task execution under the Configuration Cache. If the service was created at configuration time, the same instance is reused during the execution phase of that build. On a cache hit, when no configuration phase runs, the service is created from scratch upon the first event.

Examples of external sources include client environment variables, system properties, configuration files, shell commands, network services, among others. To represent such sources in a Gradle build in a Configuration Cache friendly way we use ValueSource. They make it possible for Gradle to transparently manage the Configuration Cache as values obtained from those sources change. For example, a build might run a different set of tasks depending on whether the CI environment variable is set or not.

A ValueSource implementation is exempt from the automatic detection of configuration cache inputs. For example, if the obtain() method reads a system property, an environment variable, or a file, those reads do not individually become configuration cache inputs. Instead, only the value returned by obtain() is tracked. If that value changes between builds, the Configuration Cache is invalidated.

This makes ValueSource the recommended escape hatch when built-in providers like providers.systemProperty(), providers.environmentVariable(), or providers.fileContents() are too limited for your use case.

You must not use these APIs directly for running processes during configuration:

The flexibility of these methods prevents Gradle from determining how the calls impact the build configuration, making it difficult to ensure that the Configuration Cache entry can be safely reused. Therefore, Gradle reports a Configuration Cache problem when it detects such an invocation. Even when the Configuration Cache is disabled, calling these methods at configuration time still emits a deprecation warning and will become an error in a future Gradle version.

If running processes is required at configuration time, you can use the configuration-cache-compatible APIs detailed below.

For simpler cases, when grabbing the output of the process is enough, providers.exec() and providers.javaexec() can be used:

For more complex cases, a custom ValueSource implementation with injected ExecOperations can be used (see Using External Information Sources for a full overview of ValueSource). This ExecOperations instance can be used at configuration time without restrictions:

You can also use standard Java/Kotlin/Groovy process APIs like java.lang.ProcessBuilder in the ValueSource.

The ValueSource implementation can then be used to create a provider with providers.of:

In both approaches, if the value of the provider is used at configuration time then it will become a build configuration input. The external process will be executed for every build to determine if the Configuration Cache is UP-TO-DATE, so it is recommended to only call fast-running processes at configuration time. If the value changes then the cache is invalidated and the process will be run again during this build as part of the configuration phase.

Plugins and build scripts may read system properties and environment variables directly at configuration time with standard Java, Groovy, or Kotlin APIs, or lazily through the value supplier APIs. Both work with the Configuration Cache: the read is correctly recorded as a build configuration input, and changing the value invalidates the cache so the build sees the new value.

The Configuration Cache report includes a list of these build configuration inputs to help track them.

The value supplier APIs — providers.systemProperty() and providers.environmentVariable() — return a Provider that resolves at execution time. Wiring the provider into a task property lets the value change without invalidating the cache, so the task simply re-runs with the new value instead of forcing a full configuration re-run.

The eager pattern reads an environment variable directly at configuration time and assigns the resolved string to a task property:

This is a valid build under the Configuration Cache. The env-var read happens during configuration and Gradle records BUILD_NUMBER as a build configuration input, so changing the value correctly invalidates the cache. The cost is that a value change re-runs the entire configuration phase, which is undesirable on CI builds where the value rotates frequently.

The deferred version uses providers.environmentVariable() and pipes the lazy provider into the task property:

Some access patterns that potentially enumerate all environment variables or system properties (for example, calling System.getenv().forEach() or using the iterator of its keySet()) are discouraged. In this case, Gradle cannot find out what properties are actual build configuration inputs, so every available property becomes one. Even adding a new property will invalidate the cache if this pattern is used.

Using a custom predicate to filter environment variables is an example of this discouraged pattern:

The logic in the predicate is opaque to the Configuration Cache, so all environment variables are considered inputs. One way to reduce the number of inputs is to always use methods that query a concrete variable name, such as getenv(String), or getenv().get():

The fixed code above, however, is not exactly equivalent to the original as only an explicit list of variables is supported. Prefix-based filtering is a common scenario, so there are provider-based APIs to access system properties and environment variables:

Note that the Configuration Cache would be invalidated not only when the value of the variable changes or the variable is removed but also when another variable with the matching prefix is added to the environment.

For more complex use cases, a custom ValueSource implementation can be used (see Using External Information Sources for a full overview of ValueSource). System properties and environment variables referenced in the code of the ValueSource do not become build configuration inputs, so any processing can be applied. Instead, the value of the ValueSource is recomputed each time the build runs and only if the value changes the Configuration Cache is invalidated. For example, a ValueSource can be used to get all environment variables with names containing the substring JDK:

Plugins and build scripts may read files directly at configuration time using standard Java, Groovy, or Kotlin APIs, or lazily through providers.fileContents(). Both work with the Configuration Cache: Gradle tracks the read via bytecode instrumentation, records the file as a build configuration input, and invalidates the cache when its contents change.

The eager pattern looks like this:

The deferred version reads the file through providers.fileContents(), so the read happens at execution time and the file becomes a task input rather than a build configuration input:

Preferring the deferred form is a good idea when the file content changes often, because a change re-runs only the affected task instead of forcing a full configuration re-run.

Here is a more complete example that reads a config file and uses its contents to compute a task input:

Gradle tracks this read and records config/title.txt as a build configuration input, so a change correctly invalidates the CC entry. The cost is that a change re-runs the entire configuration phase, not just the affected task.

The Configuration Cache-friendly version reads the file through providers.fileContents():

To detect the configuration inputs, Gradle modifies the bytecode of classes on the build script classpath, like plugins and their dependencies. Gradle uses a Java agent to modify the bytecode. Integrity self-checks of some libraries may fail because of the changed bytecode or the agent’s presence.

To work around this, you can use the Worker API with classloader or process isolation to encapsulate the library code. The bytecode of the worker’s classpath is not modified, so the self-checks should pass. When process isolation is used, the worker action is executed in a separate worker process that doesn’t have the Gradle Java agent installed.

A task that calls a problematic library directly might look like this:

The Configuration Cache-compatible version moves the call into a worker action. The worker classpath is not modified by the Gradle Java agent, so library integrity self-checks pass. With process isolation, the worker runs in a separate JVM that doesn’t have the agent installed at all:

In simple cases, when the libraries also provide command-line entry points (public static void main() method), you can also use the JavaExec task to isolate the library. The JavaExec JVM runs without the Gradle agent.

The agent also affects hot-swapping build logic classes in a running build. It prevents Hot Code Replace of such classes: Gradle logs a warning and ignores the recompiled definition. You should not rely on Hot Code Replace when debugging build logic; restart the build to pick up such a change.

The Configuration Cache serializes all non-transient fields reachable from scheduled tasks into the cache entry, which is stored under .gradle/configuration-cache in the root build directory. Sensitive values such as credentials, tokens, and API keys that are held in task state will be included in the entry.

While Java’s transient keyword can exclude individual fields from serialization, there is no Gradle-level API to selectively mark a property as "do not cache." See Selective Exclusion of Sensitive Values for the current status.

To mitigate the risk of accidental exposure, Gradle encrypts the Configuration Cache. When required, Gradle transparently generates a machine-specific secret key, caches it under the GRADLE_USER_HOME directory, and uses it to encrypt data in the project-specific caches.

To further enhance security, follow these recommendations:

For an overview, see Security Considerations. See also gradle/gradle#3972.

A common pre-Configuration Cache pattern reads a credential from an environment variable at configuration time and passes it into a task. The captured value lives on the task instance and ends up in the cache entry:

Under the Configuration Cache, System.getenv("REGISTRY_TOKEN") resolves the environment variable eagerly at configuration time, so the resolved string is captured into the task’s apiToken field and serialized into the cache entry alongside the rest of the task graph. The entry is encrypted on disk, but the plaintext value still lives inside the file. The env var also becomes a build configuration input, so rotating the token invalidates the cache on every CI build.

The Configuration Cache-friendly pattern keeps the secret in the environment variable but reads it lazily through providers.environmentVariable():

If you also want to avoid setting the env var at all — for example on a developer’s local machine — put the value in GRADLE_USER_HOME/gradle.properties (as registryToken=…​) and read it with providers.gradleProperty("registryToken") instead. gradle.properties values are Gradle-provided, not process-level env vars, and the resolved string is likewise never serialized into the CC entry.

For credentials provided to repositories specifically, use the PasswordCredentials mechanism with a credential identity prefix and let Gradle resolve it from properties or environment variables. See Basic authentication for the canonical setup.

The Configuration Cache supports third-party -javaagent: attachments to the build JVM (for example a coverage agent such as Jacoco, IntelliJ’s idea_rt.jar, or a custom user agent) in regular daemon builds and in TestKit's default (daemon) mode.

Only agents attached at JVM startup are supported. Agents attached dynamically via the Attach API after the JVM has started are not detected and may cause incorrect bytecode observation on classes loaded after attachment.

It is not supported when TestKit runs in embedded mode (withDebug(true)). To use a third-party Java agent with the Configuration Cache from there, drop withDebug(true) and let TestKit use its daemon default.

To debug the daemon TestKit spawns with the Configuration Cache enabled: