Introduction

The Jenkins Workspace Cleanup plugin removes build artifacts and temporary files after a build completes. When a build process leaves files open -- such as a Java process still running, a Docker container mounting the workspace, or a background process holding file locks -- the cleanup fails. Accumulated workspace files consume disk space and can cause subsequent builds to behave incorrectly due to stale artifacts.

Symptoms

  • Build post-build action Delete workspace fails with Unable to delete file
  • Console output shows java.nio.file.AccessDeniedException or file is being used by another process
  • Disk usage on the agent grows over time as workspaces are not cleaned
  • Subsequent builds may use stale artifacts from previous builds
  • Error message: ERROR: Unable to delete /var/lib/jenkins/workspace/my-job/target/app.jar

Common Causes

  • Build process not terminating cleanly, leaving file handles open
  • Docker containers still running and mounting workspace directories
  • Antivirus or indexing software scanning workspace files during cleanup
  • Windows agent with file locking preventing deletion of open files
  • Background processes (e.g., npm watch, webpack dev server) still running after build

Step-by-Step Fix

  1. 1.Identify the process holding the file lock: Find what is using the file.
  2. 2.```bash
  3. 3.# Linux: find processes using files in the workspace
  4. 4.lsof +D /var/lib/jenkins/workspace/my-job/
  5. 5.# Or use fuser
  6. 6.fuser -v /var/lib/jenkins/workspace/my-job/target/app.jar
  7. 7.`
  8. 8.Kill the blocking processes: Terminate processes holding locks.
  9. 9.```bash
  10. 10.# Kill all processes using the workspace
  11. 11.fuser -k -TERM /var/lib/jenkins/workspace/my-job/
  12. 12.# Force kill if TERM does not work
  13. 13.fuser -k -KILL /var/lib/jenkins/workspace/my-job/
  14. 14.`
  15. 15.Stop Docker containers mounting the workspace: Clean up container mounts.
  16. 16.```bash
  17. 17.docker ps --filter "volume=/var/lib/jenkins/workspace" -q | xargs -r docker stop
  18. 18.`
  19. 19.Configure workspace cleanup with retry and force delete: Make cleanup more resilient.
  20. 20.```groovy
  21. 21.post {
  22. 22.always {
  23. 23.// Kill any remaining processes before cleanup
  24. 24.sh 'fuser -k -TERM ${WORKSPACE} || true'
  25. 25.sleep 5
  26. 26.// Clean up with retry
  27. 27.cleanWs(disableDeferredWipeout: true, cleanupParameter: 'FAILURE')
  28. 28.}
  29. 29.}
  30. 30.`
  31. 31.Verify workspace is clean: Confirm all files are removed.
  32. 32.```bash
  33. 33.ls -la /var/lib/jenkins/workspace/my-job/
  34. 34.# Should show empty or only hidden directories
  35. 35.`

Prevention

  • Ensure build processes terminate cleanly by adding proper shutdown hooks
  • Use Docker volumes with :ro (read-only) mounts when containers do not need write access
  • Add pre-build workspace cleanup to remove stale files from previous failed builds
  • Configure agent disk space monitoring and alert when workspace directories grow excessively
  • Use cleanWs() at the beginning of pipelines to ensure a clean workspace before each build
  • Implement build timeout to prevent runaway processes from holding file locks indefinitely