robocopy: Mirror Files in CI (exit codes 0-7 succeed)

robocopy mirrors directory trees reliably, but its exit codes are bit flags: 0-7 indicate success (files copied/extra found), and only 8 and above are real failures.

robocopy is the robust copy tool for Windows. The single most common CI mistake is treating its non-zero exit as a failure: a code of 1 just means "files were copied".

What it does

robocopy copies files from a source to a destination tree. /E copies subdirectories including empty ones; /MIR mirrors the source, deleting extra files at the destination. It encodes results in an exit code where each bit is a category of outcome.

Common usage

robocopy .\build .\artifacts /E /NP /R:3 /W:5

:: mirror (destination becomes an exact copy of source)
robocopy .\dist \\server\share\app /MIR /NP

:: in PowerShell, normalize the exit code so the step does not fail
robocopy $src $dst /E /NP
if ($LASTEXITCODE -ge 8) { throw "robocopy failed ($LASTEXITCODE)" } else { $global:LASTEXITCODE = 0 }

Options

In CI

Always normalize robocopy's exit code: treat anything < 8 as success. Set /R:3 /W:5 so a transient locked file does not hang the job on the default of one million retries. Use /MIR carefully, since it deletes files at the destination that are absent from the source.

Common errors in CI

A step fails despite a perfect copy because the runner saw exit code 1 (a "files were copied" success flag) and treated non-zero as failure; remap codes 0-7 to 0. A robocopy that appears to hang is retrying a locked file under the default million-retry policy; add /R:3 /W:5. "ERROR 5 (0x00000005) Accessing Destination Directory ... Access is denied" means insufficient permissions on the target (see icacls).

Related guides