| Previous | Next |
| ERROR_UNABLE_TO_MOVE_REPLACEMENT | ERROR_JOURNAL_DELETE_IN_PROGRESS |
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2
ReplaceFile stopped after a partial namespace transition.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 is decimal 1177 (0x499). It represents the most complex of the three documented ReplaceFile-specific failures. Microsoft states that the replacement still has its original name but has inherited streams and attributes from the file it was meant to replace; the original file still exists under a different name.
Do not infer state from familiar filenames
If a backup path was supplied, that path names the original file. Without a backup, the system may use another name for the original. The replacement's data remains under its candidate name, but its metadata is no longer necessarily the metadata it had before the call.
Why this requires careful recovery
- the expected target name may not identify either surviving file
- the candidate may now carry the original file's ACLs, streams, encryption, or attributes
- the original content still exists and may be the last committed version
- a naïve retry can operate on changed identities and metadata
- temporary-file cleanup can delete the intended new content
Capture the complete post-failure layout
- directory enumeration with file names and file IDs
- hash, size, timestamps, attributes, security descriptor, and named streams for both survivors
- target, replacement, and backup arguments
- application generation or expected content version
- open handles, filter-driver activity, and namespace events around the call
Recovery procedure
Freeze further updates to the logical document. Identify which file contains the last committed data and which contains the intended replacement using hashes or application-level version markers. Preserve both, validate metadata and security, then restore one verified file to the canonical target name through a controlled operation.
Do not simply call ReplaceFile again with the original arguments: those arguments no longer describe the current namespace. Build a new recovery plan from the observed file IDs and names.
Design for restart safety
Critical software should embed a generation number or transaction identifier in the file content and persist a small replacement journal outside the files being switched. After a crash or 1177, startup can compare generations, validate checksums, and repair the target deterministically. The journal should be removed only after the canonical path is verified.
How it differs from 1175 and 1176
ERROR_UNABLE_TO_REMOVE_REPLACED leaves both files under their original names. ERROR_UNABLE_TO_MOVE_REPLACEMENT describes an earlier rename failure and may leave the target absent when no backup was requested. Error 1177 says metadata transfer and renaming have partially progressed, so recovery must inspect actual identities.
Example
A database writes a compacted file and requests a backup during replacement. The operation returns 1177: the old database now has the backup name, while the compacted candidate still has its temporary name but inherited the old file's security and streams. The service stops writers, validates both database generations, then promotes the compacted file and retains the backup for rollback.
References
- Microsoft: System Error Codes (1000–1299)
- Microsoft: ReplaceFileW function
- Microsoft: File security and access rights
Looking for a different code? Search another status or error code.