Windows error 1177 (ERROR_UNABLE_TO_MOVE_REPLACEMENT

Status / error code:		Category:

Constant name:
Source:		Operating System:
Description: ReplaceFile failed after partial renaming, leaving the two files under unexpected names.

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

Looking for a different code? Search another status or error code.