could not read workspace metadata from gradle cache

Fixes Gradle builds that fail with could not read workspace metadata from the Gradle cache. Use when a build or sync stops during configuration with a workspace metadata or cache read error. Not for a dependency download failure after configuration succeeds.

Rerun the build and copy the full path named after the error, including the cache folder and the metadata file name.

Stop all Gradle daemons with the stop command for the wrapper so no process holds the cache files open.

Check that the Gradle version running now matches the wrapper version the project pins, and note any recent upgrade or downgrade.

Rename the named workspace metadata folder to a backup name rather than deleting it outright.

Run a lightweight task such as printing the project tasks or the version first, before the full build.

Run the full build or sync that originally failed.

Resolved from the public problem: https://vectle.com/posts/pst_AcaEHqMrNYMmRTNHQSLuKw

Problem query: could not read workspace metadata from gradle cache

TL;DR:

Not specified by the original author.

TL;DR

For "files in the build cache. Looking at the cache directory the files are indeed missing, there is just a subdirectory": the practical recovery for the corrupted-cache failures: delete the bad cache files and their directories, stop and restart the Gradle daemons, and make sure your CI cleanup actually deletes directories (in Jenkins, pre-build cleanup must use deleteDirectories(true); plain file deletes are not enough).

files in the build cache. Looking at the cache directory the files are indeed missing, there is just a subdirectory

Steps

1. The practical recovery for the corrupted-cache failures: delete the bad cache files and their directories, stop and restart the Gradle daemons, and make sure your CI cleanup actually deletes directories (in Jenkins, pre-build cleanup must use deleteDirectories(true); plain file deletes are not enough). No version-specific fix was confirmed in the thread; the bug persisted across many Gradle releases, and GitHub later closed it via PR #36227. If it recurs in CI, the cleanup step above is what keeps builds green.

When to use

You are seeing this: https://github.com/gradle/gradle/issues/28974: Issue gradle/gradle#28974 (closed, 45 comments): ### Current Behavior On our Jenkins agents running on Windows we're having trouble with corrupted build cache entries. Use this skill when you run into "Transforms cache problems "Could not read workspace metadata"".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Sources

• https://github.com/gradle/gradle/issues/28974:

Issue gh:gradle/gradle#28974: the reporter asked: Issue gradle/gradle#28974 (closed, 45 comments): ### Current Behavior On our Jenkins agents running on Windows we're having trouble with corrupted build cache entries. Every couple of builds agents start to complain about missing "metadata.bin" files in the build cache. Looking at the cache directory the files are indeed missing, there is just a subdirectory "transformed/instrumented" containing a Jar. Subsequent builds will fail once this error shows up. The only solution is to delete the cache directory. Then it works for a while until the error shows up again. So far we have only seen this issue on our Windows agents. The verified answer was: The practical recovery for the corrupted-cache failures: delete the bad cache files and their directories, stop and restart the Gradle daemons, and make sure your CI cleanup actually deletes directories (in Jenkins, pre-build cleanup must use deleteDirectories(true); plain file deletes are not enough). No version-specific fix was confirmed in the thread; the bug persisted across many Gradle releases, and GitHub later closed it via PR #36227. If it recurs in CI, the cleanup step above is what keeps builds green. Evidence thread: https://github.com/gradle/gradle/issues/28974

Not specified by the original author.

TL;DR

For "Temporary workspace cannot be moved to immutable location": uninstall or disable the antivirus real-time scanner (reporters confirmed McAfee Endpoint / RAV endpoint was the culprit) and the build succeeds. Adding the.gradle folder to the antivirus exclusion list is not enough; the real-time scanner must be disabled or removed.

Temporary workspace cannot be moved to immutable location

Steps

1. The failure is caused by another process holding the temporary files open, on Windows this is almost always antivirus real-time scanning. Uninstall or disable the antivirus real-time scanner (reporters confirmed McAfee Endpoint / RAV endpoint was the culprit) and the build succeeds. Adding the .gradle folder to the antivirus exclusion list is not enough; the real-time scanner must be disabled or removed. Clean-project and clearing the Gradle caches do not help because the lock is recreated on every run.

When to use

You are seeing this: Gradle 8.6 RC builds on Windows fail with "Temporary workspace cannot be moved to immutable location" from AssignImmutableWorkspaceStep when files in the transform cache are left open. Use this skill when you run into "Gradle Temporary workspace cannot be moved to immutable location when files left open on Windows".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The thread asked: Gradle 8.6 RC builds on Windows fail with "Temporary workspace cannot be moved to immutable location" from AssignImmutableWorkspaceStep when files in the transform cache are left open. Sync attempts that worked under Gradle 8.5 break in 8.6. Multiple reporters found that antivirus software (notably McAfee endpoint real-time scanning) was holding the temporary files open, preventing Gradle from moving them into the immutable transforms cache.

The verified answer: The failure is caused by another process holding the temporary files open, on Windows this is almost always antivirus real-time scanning. Uninstall or disable the antivirus real-time scanner (reporters confirmed McAfee Endpoint / RAV endpoint was the culprit) and the build succeeds. Adding the .gradle folder to the antivirus exclusion list is not enough; the real-time scanner must be disabled or removed. Clean-project and clearing the Gradle caches do not help because the lock is recreated on every run.

Thread: https://vectle.com/threads/thr__JfBniaZHjUHSXunndH62A