Fix: Jenkins ws-cleanup Locked File Error on Windows Agents

In distributed Jenkins environments, Windows build agents often encounter failures during the post-build workspace cleanup phase. Unlike Linux, where the kernel allows unlinking a file even if it is held open by a process, the Windows NTFS filesystem and the Win32 API enforce strict file locking. When the ws-cleanup plugin or the cleanWs() step attempts to delete a directory while a handle is still open—often by a backgrounded test process, a hung compiler, or an antivirus scanner—the build fails.

The Error Log

When this issue occurs, you will typically see the following output in the Jenkins Console Log:

[WS-CLEANUP] Deleting project workspace...
[WS-CLEANUP] Deferred wipeout is used...
ERROR: Message: The process cannot access the file because it is being used by another process.
FATAL: Unable to delete 'C:\Jenkins\workspace\Project_Build_Job\node_modules\...'.
java.io.IOException: Unable to delete 'C:\Jenkins\workspace\Project_Build_Job\node_modules\...'.
    at hudson.Util.deleteFile(Util.java:271)
    at hudson.Util.deleteRecursive(Util.java:321)
    at hudson.plugins.ws_cleanup.Wipeout$DeferredWipeout.run(Wipeout.java:143)
Caused by: java.nio.file.FileSystemException: C:\Jenkins\workspace\Project_Build_Job\node_modules\...: The process cannot access the file because it is being used by another process.

---

Diagnostic Checklist

Before modifying your pipelines, perform these environment checks on the Windows Agent:

1. Process Orphans: Are there stale java.exe, node.exe, or msbuild.exe processes running under the Jenkins agent user?
2. Long Paths: Does the workspace path exceed 260 characters? Windows MAX_PATH limitations often cause deletion failures that mask themselves as “locked file” errors.
3. Antivirus/EDR: Is a security agent (e.g., Windows Defender, CrowdStrike, Carbon Black) locking the file for real-time scanning during the cleanup attempt?
4. Search Indexing: Is the Windows Search service attempting to index the workspace directory?
5. Handle Leak: Is the Jenkins agent itself or a plugin holding a log file open within the workspace?

---

The Fix

1. Enable Long Path Support (OS Level)

On Windows Server 2016 or higher (AWS EC2/Azure VM), ensure the OS is configured to handle paths exceeding 260 characters. This prevents the FileSystemException often triggered by deep node_modules structures.

Apply this via PowerShell as Administrator:

New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

2. Pipeline-Level Process Termination

Ensure all child processes are killed before the cleanup step runs. In your Jenkinsfile, use a finally block with a PowerShell command to forcibly release handles.

pipeline {
    agent { label 'windows' }
    stages {
        stage('Build') {
            steps {
                bat 'npm install && npm run build'
            }
        }
    }
    post {
        always {
            // Force kill common processes that lock files
            powershell '''
                $processes = "node", "msbuild", "csc", "vbc"
                foreach ($p in $processes) {
                    Get-Process $p -ErrorAction SilentlyContinue | Stop-Process -Force
                }
            '''
            cleanWs(
                deleteDirs: true,
                notFailBuild: true,
                disableDeferredWipeout: true
            )
        }
    }
}

3. Handle Lock Resolution via Workspace Cleanup Plugin

Configure the ws-cleanup plugin to be more aggressive. In the Jenkins Job configuration or Pipeline syntax, enable disableDeferredWipeout. Deferred wipeout moves files to a temporary location before deleting, which frequently fails on Windows due to cross-volume moves or existing locks.

If using the Workspace Cleanup Plugin GUI:

• Check “External program cleanup” and use cmd.exe /c rd /s /q %s for a more forceful OS-level deletion.

4. Environment-Wide Exclusion (Group Policy / Cloud Init)

To prevent the Windows Search Indexer and Antivirus from locking build artifacts, exclude the Jenkins root directory.

Windows Defender Exclusion (PowerShell):

Add-MpPreference -ExclusionPath "C:\Jenkins\workspace\"

Disable Indexing: Ensure the workspace folder has the “Allow files in this folder to have contents indexed” attribute unchecked. You can automate this for new directories in your build script:

attrib +I "C:\Jenkins\workspace\*" /S /D

5. Verification

After applying these changes, monitor the agent. If the error persists, use the handle.exe utility from Sysinternals to identify the specific process ID (PID) locking the file:

# Example command to run on the agent to debug
.\handle.exe -u C:\Jenkins\workspace\Project_Build_Job

By combining Long Path support, Aggressive Process Termination, and AV Exclusions, you stabilize the Windows agent environment for high-velocity CI/CD.