A step could not read, write, or create files in the workspace because the agent process lacks the right permissions. Usually a previous container step wrote files as root, or the workspace path/mount is owned by another user.
What this error means
A step fails with Permission denied when touching the workspace - mkdir: cannot create directory, error: cannot open ... Permission denied, or a failed cleanup/checkout. The build user simply cannot access files it needs.
sh 'hostname && whoami && pwd'
sh 'java -version 2>&1'
sh 'env | sort | head -40'
// workspaces are reused between builds by default
cleanWs()
Common causes
Files created as root by a container step
A docker run or container that wrote to the mounted workspace as UID 0 leaves root-owned files the agent user (often jenkins/UID 1000) cannot delete or overwrite on the next run.
Workspace path owned by another user
The workspace directory was created by a different account, or its parent is not writable by the agent process.
Read-only or restrictive mount
The workspace volume is mounted read-only, or with options that prevent the agent user from writing.
How to fix it
Run container steps as the agent user
Match the container UID to the agent user so files stay owned by it.
Jenkinsfile
docker.image('node:20').inside('-u 1000:1000') {
sh 'npm ci && npm run build'
}
Use the Workspace Cleanup plugin (cleanWs()) so each run starts clean.
Ensure the workspace volume is writable by the agent user, not read-only.
How to prevent it
Always run containers with the agent UID/GID when they touch the workspace.
Add cleanWs() (Workspace Cleanup) to pre/post steps.
Mount the workspace writable and owned by the agent user.
Frequently asked questions
What causes Jenkins workspace "Permission denied"?
There are 3 common causes: files created as root by a container step, workspace path owned by another user, and read-only or restrictive mount. A docker run or container that wrote to the mounted workspace as UID 0 leaves root-owned files the agent user (often jenkins/UID 1000) cannot delete or overwrite on the next run.
How do I fix Jenkins workspace "Permission denied"?
There are 2 fixes depending on which cause you have: run container steps as the agent user and fix ownership and clean safely. Work through them in order, since the first is the most common.
What does Jenkins workspace "Permission denied" actually mean?
A step fails with Permission denied when touching the workspace - mkdir: cannot create directory, error: cannot open ...
How do I stop Jenkins workspace "Permission denied" happening again?
Always run containers with the agent UID/GID when they touch the workspace. The prevention section lists 3 changes that keep it from recurring.
