Android Cache Fix: a Gradle plugin that works around Android build cache bugs

What the plugin actually does

Some Android plugin versions have issues with Gradle's build cache feature. When applied to an Android project, this plugin applies workarounds for these issues based on the Android plugin and Gradle versions.

That is the whole idea, and it is a small one with a large effect. The Android Gradle Plugin has, over the years, shipped tasks whose inputs were not correctly declared. A task whose inputs are wrong produces a cache key that does not describe the work, which means either a false hit, where the build reuses an output that was produced from different inputs, or a false miss, where the build redoes work that could have been reused. Both waste time, and the false hit is worse than the false miss because it is a correctness problem.

This plugin does not fix those bugs. It works around them, per version, so that a build using Android Gradle Plugin 7.2 gets the workaround for the bug introduced in 7.1 without the project having to know or care which bug is in play.

The repository is maintained by the Develocity Solutions team, as one of several publicly available repositories, and the list of siblings is worth a glance because it shows the scope of what that team maintains: the Common Custom User Data Gradle Plugin, the equivalent Maven extension and sbt plugin, the Develocity build configuration samples, the build validation scripts, the open source projects index and the Quarkus build caching extension.

The plugin is Apache 2.0 licensed, the primary language is Groovy, the default branch is main, and the last push was on 2026-10-20. The releases are v3.0.3 from 2025-11-10, v3.0.2 from 2025-10-01 and v3.0.1 from 2024-02-09, and it is published on the Gradle Plugin Portal under the id `org.gradle.android.cache-fix`.

There is a Revved up by Develocity badge pointing at a build scan, which is a small piece of dogfooding: the team that makes the build cache tooling uses the plugin in their own build.

The GitHub Actions badge is named Verify Build rather than the usual CI, which suggests the pipeline's job is to check that the plugin still builds and still applies correctly against a range of Android Gradle Plugin versions, rather than to run an application's tests.

Supported versions, and what the support actually means

The support statement is precise in a way that is worth reading closely, because build plugins often are not.

Supported Gradle versions are 7.0 and up. Supported Android Gradle Plugin versions are 7.0 and up, including alpha, beta and release candidate versions. Supported Kotlin versions are 1.7.0 and up.

The inclusion of pre-release Android Gradle Plugin versions is a deliberate choice and it is the useful part. The bugs this plugin works around are typically fixed in a pre-release before they reach a stable release, so if you are tracking a beta or release candidate of the Android plugin, you are more likely than most to hit one of them. Supporting those versions means the workaround is available before the stable release lands.

Then the caveat, which is stated at length: we only test against the latest patch versions of each minor version of the Android Gradle Plugin. Although it may work perfectly well with an older patch version, say 7.0.1, we do not test against these older patch versions, so the latest patch version is the only version from that minor release that is technically supported.

That is an honest and unusual statement. It distinguishes between what probably works and what has been verified, and it draws the line at a sensible place: patch releases within a minor version are bug fixes to the same minor release, so the latest patch is the one that represents that release's behaviour.

The configuration cache has its own condition. The plugin is compatible with the Gradle Configuration Cache when used in conjunction with Android Gradle Plugin 4.2.0 and above. Using the configuration cache with earlier versions of the Android Gradle Plugin is not supported.

This matters because the plugin's whole purpose is to change how tasks behave, and the configuration cache is exactly the mechanism that freezes how tasks are configured. A workaround that has to alter task inputs at configuration time is in tension with a cache that assumes the configuration is settled. The 4.2.0 floor is where the Android plugin's own model became compatible with that.

So the version story in one line: Gradle 7.0, Android Gradle Plugin 7.0, Kotlin 1.7.0, and configuration cache support from Android Gradle Plugin 4.2.0.

How to tell whether you need it

The README has a short section that is more useful than most of the documentation in build plugins, and it is about diagnosis rather than about the plugin.

The first question is whether to use the plugin at all: take a look at the list of issues, especially the unresolved issues. If any of these apply to your project, you can use this plugin to solve them. So the decision is driven by a symptom list rather than by a general recommendation.

The second section is how to discover the issues in the first place. You can discover issues by using the task input comparison tool in Develocity. You compare the inputs of a build that seeds the build cache, typically CI, with a build that consumes from the build cache, like a local developer build.

That workflow is the one that matters, and the direction of the comparison is the key detail. A CI build and a local build are not equivalent by construction. The CI machine has one set of environment, one JDK, one SDK installation, and the local machine has another. If the cache key differs between them, one of two things is true: the task genuinely depends on something that differs, which is legitimate, or the task's declared inputs are incomplete, which is the bug.

The task input comparison tool tells you which inputs differ. If a difference turns out to be an input the task never declared, that is the signature of a false miss and of a bug worth working around.

If you discover an issue related to the Android Gradle Plugin, the guidance is to file it in the Android Bug Tracker, and you can also file an issue in this repository so a workaround can be considered.

Both, in that order, and the reason is clear from the plugin's design. The plugin exists to work around bugs in Google's plugin, so a new bug has to reach Google to be fixed properly, and this repository's issue tracker is where someone can determine in the meantime whether a workaround is feasible. A project that filed only one of the two would either produce a workaround for something that was never reported upstream, or fail to get the underlying bug fixed.

The unresolved issues section reinforces the point. It lists issues fixed by the plugin but unresolved in any current or upcoming preview release of the Android Gradle Plugin, and issues not fixed by the plugin because it has no workaround. It also asks you to vote for the linked issues if you are experiencing them in your project, which is the mechanism by which a workaround gets prioritised over the others.

Applying it, and the convention plugin route

The plugin should be applied anywhere the `com.android.application` or `com.android.library` plugins are applied, and the recommendation is to add it to your project's conventions plugin.

A conventions plugin is the Gradle mechanism for sharing build logic across subprojects: a plugin of your own that applies the common configuration, so each module's build file stays short and the shared setup lives in one place. Applying this plugin there means every Android module gets the workaround without anyone remembering to add it.

The Kotlin version of that setup has two files. The convention plugin's own build declares the dependency:

// in build.grade.kts for convention plugin build
dependencies {
  // ...
  implementation("org.gradle.android.cache-fix:org.gradle.android.cache-fix.gradle.plugin:3.0.2")
  // ...
}

// in com.myconventions.build.gradle.kts
plugins {
    id("com.android.application") // or "com.android.library"
  // Add this next line to your existing convention plugin.
    id("org.gradle.android.cache-fix")
}

The Groovy equivalent is the same shape with different syntax, and the comment placement differs slightly, which is a hint that these snippets were kept in step with the actual convention plugin files rather than generated from each other.

If you are not using convention plugins and want a quick way of testing the plugin, you can place it in the root project's build file instead. The Groovy form of that is:

plugins {
    id "org.gradle.android.cache-fix" version "3.0.2" apply false
}

subprojects {
    plugins.withType(com.android.build.gradle.api.AndroidBasePlugin) {
        project.apply plugin: "org.gradle.android.cache-fix"
    }
}

The `apply false` in the plugins block and the `plugins.withType` hook in the subprojects block are the two details that make this work. `apply false` declares the plugin on the root project without applying it there, and the `withType` callback fires when a subproject applies an Android plugin, at which point the cache fix plugin is applied to that subproject.

That mechanism is more careful than applying the plugin unconditionally to every subproject, because a non-Android subproject would not have the tasks the workarounds target.

The README discourages the root-project approach because it uses cross project configuration. That is a real and specific objection rather than a general one, and the distinction the Gradle documentation draws is between convention plugins, where shared logic is applied by each project independently, and cross configuration, where the root project reaches into the subprojects to configure them. The second form is the one that interacts badly with the configuration cache, which is the same mechanism this plugin cares about, so the advice and the reason line up.

How the workarounds are organised

The last section explains where the workarounds live and how they are documented, and it is the part that makes the plugin maintainable rather than a pile of patches.

You can take a look at the list of issues that the plugin fixes by looking at the classes in `org.gradle.android.workarounds`. It contains a number of `Workaround` implementations annotated with `@AndroidIssue`. The Javadoc has a short description of the problem, and the annotation gives information about when the problem was introduced, what is the first version of the Android plugin that fixes it, and there is a link to the issue on Android's issue tracker.

So the design is one class per bug, each annotated with the metadata needed to decide whether it applies to the version of the Android plugin in front of you. The introducedIn and fixedIn fields are the important ones, because they let the plugin answer the question for itself: given the Android Gradle Plugin version in this build, is this workaround in the window where it applies?

That is what makes it possible for the plugin to support a range of versions without a lookup table maintained by hand, and it is why the project can keep supporting Android Gradle Plugin 7.0 through the current releases with a single rule rather than a list.

The example shows the shape:

/**
 * Fix {@link org.gradle.api.tasks.compile.CompileOptions#getBootClasspath()} introducing relocatability problems for {@link AndroidJavaCompile}.
 */
@AndroidIssue(introducedIn = "3.0.0", fixedIn = "3.1.0-alpha06", link = "https://issuetracker.google.com/issues/68392933")
static class AndroidJavaCompile_BootClasspath_Workaround implements Workaround {
    // ...
}

Two things are visible there. The class name is the task name and the symptom, which is a naming convention that makes the list of workarounds readable without opening each one. And the fixedIn value is a pre-release, `3.1.0-alpha06`, which matches the note that pre-release versions are supported: a workaround that stopped applying at 3.1.0-alpha06 would have covered a window that included alphas and betas, and the plugin needed to know the exact pre-release to get that boundary right.

The Javadoc carries the human-readable explanation, the annotation carries the machine-readable metadata, and the issue tracker link ties it back to the upstream report. A maintainer reading the list can tell what each class does, when it is needed, and where the discussion is, and a user reading the same list can tell whether their Android plugin version falls in the affected window.

The repository layout supports this: a `src/` directory holding the plugin, a `config/` directory, a `docs/` directory, a `release/` directory, the Gradle build files, and `AGENTS.md` and `CLAUDE.md` at the root for the working conventions.

Editorial conclusion

Adopt the Android Cache Fix plugin if your CI and local builds disagree about cache hits and you have traced the cause to a known Android Gradle Plugin bug, since that is exactly the situation it exists for. Do not adopt it as a general performance tool, because it does nothing for problems that are not on its list of known issues, and check first whether the underlying bug has since been fixed upstream, since the plugin tracks that and drops workarounds for versions that no longer need them.

Frequently asked questions

Official sources

1. gradle/android-cache-fix-gradle-plugin on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases