Jenkins cleanWs Failed - Fix Workspace Cleanup Errors

By Daniel Zoghalchali·Latchkey

The cleanWs() step (Workspace Cleanup plugin) could not clear the workspace. Files are locked by a running process or were created root-owned by a container step, the plugin is not installed, or the cleanup ran where the files are not.

What this error means

A cleanWs() step warns or fails - Cannot delete a path, a permission error, or No such DSL method 'cleanWs' if the plugin is absent. The workspace is left partly populated and the next run may inherit stale or root-owned files.

Jenkins console

[WS-CLEANUP] Deleting project workspace...
ERROR: Cannot delete workspace: /home/jenkins/workspace/app/build/out:
Permission denied
# or, plugin missing:
No such DSL method 'cleanWs' found among steps [...]

Diagnose it: agent, workspace, or sandbox?

Jenkinsfile

sh 'hostname && whoami && pwd'
sh 'java -version 2>&1'
sh 'env | sort | head -40'

// workspaces are reused between builds by default
cleanWs()

Common causes

Root-owned or locked files block deletion

A container step that wrote as UID 0, or a process still holding files open, leaves paths the agent user cannot delete during cleanup.

Plugin missing or cleanup on the wrong node

Without the Workspace Cleanup plugin, cleanWs is unknown. Running it on a different agent/dir than the build leaves the real workspace untouched.

How to fix it

Run containers as the agent user and clean in post

Match container UID to the agent so files stay deletable, and clean up in a post { cleanup } block on the same node.

Jenkinsfile

pipeline {
  agent { label 'linux' }
  stages {
    stage('Build') {
      steps { sh 'docker run --rm -u 1000:1000 -v $PWD:/w -w /w node:20 npm ci' }
    }
  }
  post { cleanup { cleanWs() } }
}

Force-clean stubborn paths

Install the Workspace Cleanup plugin if cleanWs is unknown.
Reset ownership of stray root-owned files before cleanup (run a container as root to chown/rm them).
Run cleanWs() on the same agent that holds the workspace, in a post block.

How to prevent it

Run workspace-touching containers with the agent UID/GID.
Clean the workspace in post { cleanup } on the build’s own node.
Keep the Workspace Cleanup plugin installed where pipelines call cleanWs.

Frequently asked questions

What causes Jenkins cleanWs failed?

There are 2 common causes: root-owned or locked files block deletion and plugin missing or cleanup on the wrong node. A container step that wrote as UID 0, or a process still holding files open, leaves paths the agent user cannot delete during cleanup.

How do I fix Jenkins cleanWs failed?

There are 2 fixes depending on which cause you have: run containers as the agent user and clean in post and force-clean stubborn paths. Work through them in order, since the first is the most common.

What does Jenkins cleanWs failed actually mean?

A cleanWs() step warns or fails - Cannot delete a path, a permission error, or No such DSL method 'cleanWs' if the plugin is absent.

How do I stop Jenkins cleanWs failed happening again?

Run workspace-touching containers with the agent UID/GID. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation