Gradle "Could not open ... cache" - Fix Corrupt Gradle Cache in CI

Gradle could not open one of its on-disk caches under ~/.gradle/caches. A previous build that was interrupted or OOM-killed left a half-written cache entry, and the next build cannot read it.

What this error means

The build fails early with Could not open <cp_proj|cp_settings|cache> generic class cache for ..., often citing a .bin file. Deleting ~/.gradle/caches and rebuilding fixes it, which points squarely at a corrupt cache.

gradle output

* What went wrong:
Could not open cp_proj generic class cache for build file
'/workspace/build.gradle' (/root/.gradle/caches/8.8/scripts/.../classes).
> Could not read workspace metadata ... (corrupt)

Common causes

Corrupt cache from an interrupted build

An OOM-kill, a runner timeout, or a SIGKILL mid-write leaves a partially-written cache file. Gradle cannot deserialize it on the next run.

Stale cache restored across incompatible builds

A CI cache restored from a different Gradle version or a different machine layout can leave entries Gradle refuses to open.

How to fix it

Clear the corrupt cache and rebuild

Remove the cache directory and let Gradle rebuild it from scratch.

Terminal

rm -rf ~/.gradle/caches
./gradlew clean build

Key the CI cache so corruption cannot persist

Version the cache key by Gradle version and build scripts, and avoid saving the cache from a failed run.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.gradle/caches
    key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', 'gradle/wrapper/gradle-wrapper.properties') }}

How to prevent it

Do not persist ~/.gradle/caches from interrupted/OOM-killed runs.
Version the cache key by Gradle version and build scripts.
Right-size memory so builds are not OOM-killed mid-write.