File migrations and large-scale directory synchronization are routine administrative responsibilities. However, relying on the standard Windows File Explorer GUI or legacy command-line tools like copy and xcopy frequently results in failed operations: long file path limits exceed 260 characters, network drops abort multi-gigabyte transfers, file timestamps reset, and NTFS Access Control Lists (ACLs) are stripped.
Microsoft's standard for enterprise data replication is Robocopy (Robust File Copy). Built natively into Windows 11 and Windows Server, Robocopy provides multithreaded transfer engines, comprehensive metadata and security preservation, intelligent retry mechanisms, and bitmask exit codes designed for automated scripts.
Core Syntax and Operational Flags
Robocopy follows a standardized syntax: robocopy <source> <destination> [file...] [options].
| Category | Switch | Functional Behavior | Operational Guidance |
|---|---|---|---|
| Copy Scope | /E |
Copies all subdirectories, including empty ones. | Standard recursive directory tree duplication. |
| Mirroring | /MIR |
Mirrors source tree to destination (equivalent to /E /PURGE). |
Caution: Deletes any destination file that does not exist in the source! |
| Performance | /MT:n |
Enables multithreaded copying using n threads (1 to 128; default is 8). |
Dramatically accelerates transfers of millions of small files over fast networks (e.g., /MT:32). |
| Restartability | /Z |
Enables restartable mode for network file transfers. | If connection drops mid-file, Robocopy resumes transfer where it left off instead of restarting from byte 0. |
| Metadata | /COPYALL |
Copies all file info (/COPY:DATSOU). |
Preserves Data, Attributes, Timestamps, Security (ACLs), Owner info, and Auditing info. |
| Logging | /NP /NDL /TEE |
Suppresses progress percentage (/NP) and directory lists (/NDL); outputs to console and log (/TEE). |
Keeps automation log files clean and performant. |
The Danger of /MIR (Mirror Mode): The /MIR switch enforces parity. If the target destination directory already contains existing corporate data that is absent from the source path, Robocopy will permanently purge those files from the destination without sending them to the Recycle Bin. Always run a trial simulation with /L (List Only mode) before executing a mirror command in production.
Preserving Security & Permissions: /COPY Flags
When migrating shared folders between Windows file servers, preserving NTFS permissions is critical. Robocopy provides granular control via the /COPY flag:
| Flag Code | Preserved Metadata Element | Administrative Requirement |
|---|---|---|
| D | Data (file payload contents) | Standard read permissions. |
| A | Attributes (Read-Only, Hidden, System, Archive) | Standard write permissions. |
| T | Timestamps (Created, Modified, Last Accessed) | Ensures file modification times match original source. |
| S | NTFS Security (Discretionary ACLs) | Preserves explicit and inherited access rights. |
| O | Owner information | Requires Restore Files and Directories administrative user right. |
| U | Auditing information (System ACLs) | Requires Manage Auditing and Security Log administrative right. |
For standard enterprise file server migrations, administrators typically use /COPY:DATS or /COPYALL to guarantee full permission fidelity.
Configuring Network Resilience: Avoiding Default Hangs
By default, if Robocopy encounters a locked file or temporary network disconnect, its default retry settings are catastrophic for automation:
- Default Retries (
/R): 1,000,000 retries - Default Wait Time (
/W): 30 seconds
Under default settings, a single locked file causes Robocopy to stall for up to 347 days! In production scripts, always explicitly override these parameters:
# Restrict retries to 3 attempts with a 5-second wait between attempts
robocopy C:\Source D:\Dest /R:3 /W:5Production Migration Command Example
A battle-tested production command for migrating enterprise file shares over an internal LAN:
robocopy "\\Server01\FinanceShare" "\\Server02\FinanceShare" *.* /E /COPYALL /ZB /MT:32 /R:3 /W:5 /FFT /V /TS /FP /NP /LOG:"C:\MigrationLogs\FinanceShare_Migration.log" /TEECommand breakdown:
/ZB: Uses restartable mode; if access is denied, automatically falls back to administrative Backup Mode to bypass file locking./MT:32: Spawns 32 parallel worker threads for high-speed file transfers./FFT: Uses FAT file timing (2-second precision tolerance), preventing false-positive re-copies across heterogeneous network storage (e.g., Linux SMB/NAS)./LOG:... /TEE: Writes detailed timestamps and full paths to a log file while simultaneously displaying summary output in the terminal.
Interpreting Robocopy Return Codes in Automation
Unlike standard Windows utilities where an exit code of 0 is the only success indicator, Robocopy uses a bitmask return code architecture:
| Exit Code | Hex Bit | Operational Meaning | Script Evaluation |
|---|---|---|---|
| 0 | 0x00 |
No errors occurred, but no files were copied (source and destination are already in sync). | Success (Clean No-Op) |
| 1 | 0x01 |
One or more files were copied successfully. | Success |
| 2 | 0x02 |
Extra files exist in destination that are not in source. No files failed. | Success (Extras Present) |
| 4 | 0x04 |
Some mismatched files or directories were detected. | Success (Mismatches Resolved) |
| 8 | 0x08 |
Several files failed to copy (access denied, file locked, network dropped). | Failure / Warning |
| 16 | 0x10 |
Fatal error: Robocopy did not copy any files (invalid syntax, unreachable share). | Fatal Failure |
In PowerShell scripts, any exit code less than 8 represents a successful execution:
# Correct PowerShell error evaluation for Robocopy
robocopy "\\Source\Data" "D:\Data" /E /R:2 /W:2
$rc = $LASTEXITCODE
if ($rc -ge 8) {
Write-Error "Robocopy failed with exit code $rc. Inspect migration log!"
} else {
Write-Host "Robocopy completed successfully with status $rc." -ForegroundColor Green
}