Skip to content

Validation Rules and Exit Codes

Andrew Paolucci edited this page Nov 19, 2026 · 2 revisions

Validation Rules & Exit Codes

robocopy2rust-core pairs an upfront 16-rule static validator (validation.rs) with an exact Microsoft Robocopy 0..=16 bitmask decoder (exit_code.rs).


Pre-Flight Validation Rules (validate_job)

Validation runs continuously in both GUIs, before every robocopy2rust run/dry-run CLI command, and before MCP tool execution. Any Error-severity finding blocks live execution cleanly with remediation guidance.

Code Severity Condition Triggered Suggested Remediation
MISSING_SOURCE Error Source path is empty (unless /NOSD or /JOB: is specified) Select a Source folder or enable /NOSD with a /JOB file
MISSING_DEST Error Destination path is empty (unless /NODD or /JOB: is specified) Select a Destination folder or enable /NODD with /QUIT
SAME_SRC_DST Error Normalized Source and Destination resolve to the exact same path Choose a separate Destination directory
RECURSIVE_DEST_IN_SRC Warning Destination is nested inside Source while /S, /E, or /MIR is active Exclude the destination path via /XD to prevent infinite recursion
MT_OUT_OF_RANGE Error /MT:n is < 1 or > 128 Set thread count between 1 and 128
MT_INCOMPATIBLE_IPG Error /MT is combined with /IPG (Inter-Packet Gap) Disable /MT or clear /IPG
MT_INCOMPATIBLE_EFSRAW Error /MT is combined with /EFSRAW Disable /MT when copying encrypted files in raw EFS mode
MT_INCOMPATIBLE_LFSM Error /MT is combined with /LFSM or /LFSM:floor Disable /MT when Low Free Space Mode is active
LFSM_INCOMPATIBLE_EFSRAW Error /LFSM is combined with /EFSRAW Disable either /LFSM or /EFSRAW
MIR_WITH_MOVE Warning /MIR is combined with /MOV or /MOVE Can delete from both Source and Destination; test with /L first
CREATE_WITH_MOVE Warning /CREATE is combined with /MOV or /MOVE Disable /MOV//MOVE when creating zero-byte skeleton trees
INVALID_RUN_HOURS Error /RH:value does not match valid 24-hour HHMM-HHMM (0000–2359) Use four-digit 24h start and end times separated by a hyphen (e.g., 2200-0600)
INVALID_SIZE_SPEC Error /IoMaxSize, /IoRate, /Threshold, or /LFSM floor is not integer + optional K/M/G Use formats such as 64K, 25M, 2G, or plain bytes (is_valid_kmg_spec)
BACKUP_IGNORES_X Info Copy flag X (Skip Alt Data Streams) is enabled alongside /B or /ZB Informational: Robocopy ignores flag X under backup privilege mode
BACKUP_PRIVILEGE_NOTE Info /B or /ZB is enabled May require Administrator privileges (SeBackupPrivilege & SeRestorePrivilege)
DESTRUCTIVE_FLAGS_ACTIVE Warning /MIR, /PURGE, /MOVE, or /MOV is active without /L Dry-Run Run a Dry-Run (/L) preview first to inspect planned deletions

Microsoft Robocopy Exit Code Bitmask (0..=16)

Unlike conventional POSIX/Windows utilities where 1 indicates failure, Microsoft Robocopy returns a bitmask where exit codes 0 through 7 are successful and 8 or higher indicate failure. CI pipelines, PowerShell, and Task Scheduler treat raw exit code 1 as an error unless wrapped cleanly!

Individual Bit Definitions

Bitmask Decimal ExitCodeSeverity Contribution Meaning
0x00 0 Success No files copied, no failures, source and destination already synchronized
0x01 1 SuccessWithChanges One or more files were copied successfully (new or updated files)
0x02 2 SuccessWithNotices Extra files or directories were detected in the destination
0x04 4 SuccessWithNotices Mismatched files or directories were detected (housekeeping check recommended)
0x08 8 CopyError (Failure) One or more files or directories could not be copied after /R:n retries
0x10 16 FatalError (Failure) Serious/fatal error (invalid parameters, missing path, or access denied)

Full Exit Code Table

Code Bits Active is_success Short Label (decode_exit_code) Severity
< 0 Process killed / cancelled false Cancelled / Terminated Cancelled
0 0x00 true 0 - No Changes Success
1 0x01 true 1 - Files Copied SuccessWithChanges
2 0x02 true 2 - Extra Files SuccessWithNotices
3 0x01 | 0x02 true 3 - Copied + Extra SuccessWithNotices
4 0x04 true 4 - Mismatches SuccessWithNotices
5 0x01 | 0x04 true 5 - Copied + Mismatches SuccessWithNotices
6 0x02 | 0x04 true 6 - Extra + Mismatches SuccessWithNotices
7 0x01 | 0x02 | 0x04 true 7 - Copied + Extra + Mismatches SuccessWithNotices
8 0x08 false 8 - Copy Failures CopyError
9..=15 Includes 0x08 false <code> - Error (Bitmask) CopyError
16 0x10 false 16 - Fatal Error FatalError
> 31 Non-standard OS bits (!0x1F) false <code> - Error (Bitmask) FatalError

Normalized vs. Raw Exit Behavior

  • robocopy2rust dry-run / run (Default): Returns exit code 0 to the calling shell whenever Robocopy returns 0..=7 (res.exit_info.is_success), and returns non-zero (res.exit_code.max(1)) on >= 8 or cancellation (-1 → 1). This makes robocopy2rust natively safe in CI, Task Scheduler, and PowerShell $ErrorActionPreference = 'Stop' workflows.
  • --raw-exit-code: Preserves the literal underlying Robocopy bitmask (0..=16) when downstream tooling inspects bit flags directly.
  • Exported .bat / .ps1 Scripts: Generated wrapper scripts also normalize codes 0..=7 to exit 0 and abort only when %RC% GEQ 8 / $rc -ge 8.

Clone this wiki locally