skip to content

What does the STABLE_CONFIGURATION_CACHE feature flag do, and why would you enable it before the configuration cache is even turned on?

level: seniorimportance: should knowfreq 32%

answer

  1. enableFeaturePreview in settings
  2. stricter checks even with cache off
  3. decouple validation from adoption
  4. migration backlog to zero
  5. became default in newer Gradle

basics

~10 s

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.

solid answer

~50 s

`STABLE_CONFIGURATION_CACHE` is a Gradle **feature preview**, enabled via `enableFeaturePreview("STABLE_CONFIGURATION_CACHE")` in `settings.gradle(.kts)`. It applies the *stricter* set of configuration-cache requirements — including additional checks that were being stabilised — regardless of whether the configuration cache itself is active. The point is **decoupling validation from adoption**: you can flip the preview on, keep running your normal (cache-off) builds, and Gradle will now flag patterns that would be illegal under the cache (e.g. certain late `Project` access). This lets a team find and fix incompatibilities incrementally without paying for or debugging an actually-cached build. It's effectively a migration aid: turn it on, drive the warnings/errors to zero, then enable the configuration cache for real with confidence. In recent Gradle versions these stricter checks became the default, so the flag matters mainly for codebases on the versions where it was still a preview.

code

kotlin · 5 lines
kotlin
// settings.gradle.kts
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")

// Now a normal build (no --configuration-cache) still reports
// configuration-cache rule violations, letting you fix them early.

go deeper

for a junior

Know it is a feature preview that enables stricter config-cache checks.

for a middle

Explain the settings-level enableFeaturePreview call and that checks run even with the cache off.

for a senior

Articulate the decouple-validation-from-adoption migration strategy and the BuildFeatures interaction.

for a principal

Position it in a rollout plan: enable preview fleet-wide, burn down violations as a tracked backlog, then enable the cache in CI; note the version where it became default.

## What a feature preview is Gradle ships some behaviour behind **feature previews** — opt-in flags declared in settings that let you adopt forthcoming defaults early: ```kotlin // settings.gradle.kts enableFeaturePreview("STABLE_CONFIGURATION_CACHE") ``` Previews are a controlled on-ramp: you accept slightly-ahead-of-default behaviour in exchange for early validation and a smoother future upgrade. ## What STABLE_CONFIGURATION_CACHE changes The configuration cache enforces rules at execution time (no live `Project` references, captured state must be serializable/declared, etc.). As the cache matured, Gradle tightened those checks. `STABLE_CONFIGURATION_CACHE` enables that **stricter** rule set. The key property: the stricter checks run **even when the configuration cache is not active**. So a normal `./gradlew build` (cache off) will still report violations of cache requirements. ## Why enable it before turning the cache on Migrating to the configuration cache is mostly about eliminating incompatibilities across your build logic and plugins. Doing that with the cache *on* means every iteration pays serialization cost and you debug through cache-specific failures. With the preview flag you instead: 1. Enable `STABLE_CONFIGURATION_CACHE`. 2. Run ordinary builds; collect the stricter-check violations. 3. Fix them (migrate APIs, inject services, capture providers). 4. Once clean, enable the configuration cache for real — adoption is now low-risk. This **decouples validation from adoption** and turns a big-bang switch into incremental cleanup. ## Interaction with BuildFeatures `BuildFeatures.configurationCache.active` still reports whether the cache is genuinely caching. The preview flag does not make `active` true — it only raises the strictness of checks. So you can have the stricter checks on (preview enabled) while `active` is false because you haven't turned the cache on yet. ## Version context This was a transitional mechanism: in newer Gradle releases the stricter checks became the default and the configuration cache itself graduated to stable, so the preview is most relevant when working on a codebase pinned to a version where it was still opt-in. Mentioning that nuance signals real-world awareness. ## Practical guidance - Put `enableFeaturePreview("STABLE_CONFIGURATION_CACHE")` in `settings.gradle.kts`, not a build script. - Treat its output as a migration backlog; drive it to zero before enabling `--configuration-cache` in CI. - Combine with `BuildFeatures` gating in plugins so unmigrated paths degrade gracefully meanwhile.

  • Where must enableFeaturePreview be declared?
    In settings.gradle / settings.gradle.kts — feature previews are a settings-level concern, not a build-script one.
  • Does enabling the flag make BuildFeatures.configurationCache.active return true?
    No. It only raises the strictness of checks; active stays false until you actually turn the configuration cache on.

saying these in an interview costs you the question

  • Claiming the flag turns the configuration cache on (it only tightens checks).
  • Putting enableFeaturePreview in a build.gradle instead of settings.
  • Thinking active becomes true just because the preview is enabled.

context

resolving links…