Android Build Error 'Unable to delete file': Stop the Lock, Clean the Cache, Rebuild
A developer whose builds fail on 'Unable to delete file' can confirm whether a locked cache file is the culprit within minutes, and the fix works without touching code or plugin versions.
Android builds occasionally die with 'Unable to delete file .../file-map.txt' during cache cleanup. The cause is a file handle held by a running process: the Gradle daemon, an IDE's indexing thread, or security software scanning the build directory. The error is not a code or configuration problem.
The fix is a sequence of stops and cleans. Exit any IDE that has the project open, run `./gradlew --stop` to shut down the daemon, remove `app/build` and `.gradle`, then rebuild with `./gradlew clean assembleDebug` or the IDE's Clean Project and Rebuild. If the error persists, `lsof | grep file-map.txt` shows the PID holding the file, and a system restart releases everything.
Prevention is straightforward: don't build from two tools at once, stop the daemon before cleanup, and suspect process locks before touching business code or plugin versions.
Checking for process locks before modifying code or Gradle configuration prevents hours of debugging a symptom that stems from file ownership, not build logic.
Gradle's daemon, which speeds up builds by staying alive, is a common source of stale file handles; stopping it before cleaning caches is a reliable first move.