Gradle "Could not read workspace metadata from metadata.bin" in CI

By Daniel Zoghalchali·Latchkey

Gradle tried to read a transform result from its cache and the metadata.bin for that entry was missing or unreadable. The cached artifact-transform directory is corrupt, typically because a previous build was cancelled while writing it.

What this error means

The build fails with "Could not read workspace metadata from <gradle home>/caches/transforms-4/<hash>/metadata.bin". It often appears after a cancelled job and reproduces until the cache is cleared.

> Could not read workspace metadata from
  /home/runner/.gradle/caches/transforms-4/0e69aaacf4af78f6c6c3f80936fa8b36/metadata.bin

Common causes

An interrupted build left a half-written cache entry

A cancelled or killed job stopped Gradle mid-write, so the transform directory has the transformed output but no valid metadata.bin.

A restored CI cache carried the corruption forward

A cache action saved the broken transforms directory, so every later run restores the same unreadable entry.

How to fix it

Delete the corrupt transforms cache

1. Remove the affected transforms-* directory under the Gradle home.
2. Re-run the build so Gradle regenerates the transform from scratch.
3. If a CI cache restored it, invalidate that cache key so the bad entry stops returning.

rm -rf ~/.gradle/caches/transforms-*
./gradlew build

Avoid caching a half-written Gradle home

Save the Gradle cache only on successful runs, and bump the cache key so a previously corrupted entry is not restored.

- uses: actions/cache@v4
  with:
    path: ~/.gradle/caches
    key: gradle-${{ hashFiles('**/*.gradle*') }}-v2

How to prevent it

• Avoid caching the Gradle home from cancelled or failed runs.
• Rotate the cache key when corruption appears so it is not restored.
• Let jobs finish cleanly instead of force-cancelling mid-write where possible.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation