Skip to main content
but also sets ACL and attribute mirroring. `/PURGE` alone only deletes items excluded by file/directory filters. Use `/MIR` for full sync

Robocopy PowerShell: CLI Reference and Exit Code Handling

3 min read

robocopy with powershell is the practice of invoking the Windows robocopy executable from PowerShell scripts while correctly capturing exit codes, passing arguments, and handling cross-domain authentication for reliable file replication.

# Basic usage with exit code capture
$result = robocopy C:source \servershare /MIR /R:2 /W:5
if ($LASTEXITCODE -ge 8) { Write-Error "Copy failed"; exit $LASTEXITCODE }

Overview

Calling robocopy from PowerShell requires careful handling of exit codes, argument splitting, and cross-domain credentials. The following examples address these complexities to ensure robust automation.

Syntax

# Direct invocation (arguments as separate tokens)
robocopy $source $dest /MIR /COPYALL /B /SEC /R:3 /W:5 /MT:16 /LOG+:$logfile

# Using a string for options (requires splatting or splitting)
$what = "/COPYALL /B /SEC /MIR /R:3 /W:5"
$options = $what -split ' '
robocopy $source $dest $files $options

# Full pattern with exit code capture
$result = robocopy $source $dest $files $options
Write-Host "Exit code: $LASTEXITCODE"

Options and Flags

Flag Type Default Description
/MIR Option N/A Mirror source to destination (copies and deletes). Equivalent to /PURGE + /E.
/COPYALL Option N/A Copy all file info (data, attributes, timestamps, security, ownership, audit).
/B Option N/A Copy in Backup mode – bypasses file permission checks (requires admin/SeBackupPrivilege).
/SEC Option N/A Copy NTFS security (ACLs) along with files.
/R:3 Numeric 1 million Number of retries on failed copies. Use low value in scripts to avoid hangs.
/W:5 Numeric 30 Wait time (seconds) between retries. Reduce to speed up failure detection.
/MT:16 Numeric 8 Multi-threaded copy with N threads (1–128). Significantly speeds up many small files.
/LOG+: File N/A Append output to log file (avoids overwriting).
-im Flag N/A Include modified files (same as /IM? Not standard robocopy – likely custom alias. Use /IM for include modified).
-in Flag N/A Include (same as /IN? Not standard. Use /IA: or /IF for file filter).
-lt Flag N/A Later than – filter copied files by date. Use /MAXAGE: or /MINAGE: instead.
-mhe Flag N/A Modify handle? Not a robocopy flag – possibly misremembered.
-ne Flag N/A Newer than – use /MAXAGE: or /MINAGE: or /XO (exclude older).
-r Flag N/A Restart mode – use /Z (restartable mode) or /ZB (backup + restart).

Note: Flags marked with -im, -in, -lt, -mhe, -ne, -r are not standard robocopy flags. They likely originate from a custom wrapper or misremembered parameter. Use the documented equivalents shown above.

Usage Examples

Example 1: Mirror with error logging and exit code check

$source = "\FileServer01ShareA"
$dest   = "\FileServer02BackupA"
$log    = "C:Logsrobocopy_$(Get-Date -Format 'yyyyMMdd-HHmmss').log"

robocopy $source $dest /MIR /COPYALL /B /R:2 /W:3 /LOG+:$log

if ($LASTEXITCODE -ge 8) {
    Write-Error "Robocopy failed with exit code $LASTEXITCODE. Check log: $log"
    exit $LASTEXITCODE
} else {
    Write-Host "Copy completed with exit code $LASTEXITCODE"
}

Mirrors two shares across servers. Exit codes 0–7 are considered successful (some warnings). Code 8 or higher indicates at least one failure; script stops and logs the error.

Example 2: Multi-threaded copy with exclusions and resume

$src = "D:Data"
$dst = "E:Backup"
$exclude = @("*.tmp", "*.log", "*.bak")
$filter = "/IF *.pdf *.docx *.xlsx"  # copy only these types
$options = @("/MIR", "/MT:32", "/Z", "/R:5", "/W:10", $filter)

# Exclude files via /XF
$excludeOpts = $exclude | ForEach-Object { "/XF", $_ }
$allOptions = $options + $excludeOpts

robocopy $src $dst $allOptions

Uses multi-threaded mode with 32 threads, restartable mode (/Z) for large files, and restricts copied files to specific extensions while excluding temporary files.

Example 3: Cross-domain authentication using New-PSDrive

$creds = Get-Credential
$sourceDrive = New-PSDrive -Name Src -PSProvider FileSystem -Root "\RemoteServerShare" -Credential $creds
$destDrive  = New-PSDrive -Name Dst -PSProvider FileSystem -Root "\TargetServerBackup" -Credential $creds

robocopy "Src:" ""Dst:"" /MIR /COPYALL /R:3 /W:5 /NDL /NFL

Remove-PSDrive Src