What does Windows error code 1176 (ERROR_UNABLE_TO_MOVE_REPLACEMENT) mean?

 
Previous Next
ERROR_UNABLE_TO_REMOVE_REPLACED ERROR_UNABLE_TO_MOVE_REPLACEMENT_2

ERROR_UNABLE_TO_MOVE_REPLACEMENT

The replacement file could not be renamed into the target name.

ERROR_UNABLE_TO_MOVE_REPLACEMENT has value 1176 (0x498) and is returned by ReplaceFile. The precise post-failure state depends on the optional backup parameter, so generic “replace failed” handling is unsafe.

State documented by ReplaceFile

  • if a backup name was supplied, the original target and replacement retain their original names
  • if no backup name was supplied, the original target no longer exists and the replacement remains under its original name

The second case is especially important: the expected target path can be absent even though the new data still exists in the temporary replacement file. A cleanup routine that deletes all temporary files could then destroy the only surviving copy.

Possible causes

  • rename or delete access is blocked by ACLs or sharing modes
  • another process changes one of the paths during the operation
  • security software intercepts the namespace transition
  • the replacement directory state changes after validation
  • the application violates the same-volume requirement

Required diagnostic record

  • all three path parameters and whether the backup parameter was null
  • file existence, file ID, size, and hash at each path after failure
  • caller token, relevant access rights, and sharing conflicts
  • flags passed to ReplaceFile
  • the expected target version or generation

Recovery logic

First inspect the actual namespace and branch on the backup case. If the target path is absent but the replacement survives, keep the replacement and either retry the rename after revalidation or restore a known-good target. If both original names remain, resolve the conflict and retry the complete replacement.

Do not claim success merely because the candidate file contains correct data; callers normally depend on the target name and metadata transition. Likewise, do not recreate the target from an older backup until checking whether the replacement is the latest durable version.

Implementation recommendations

Persist an operation record before calling ReplaceFile: target, candidate, backup, expected file IDs, and transaction generation. Startup recovery can then inspect all paths and choose the newest valid content without relying on filename suffixes. Temporary-file scavengers must exclude active replacement records.

Comparison with companion errors

ERROR_UNABLE_TO_REMOVE_REPLACED leaves both original names intact. ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 indicates a later partial state in which the original may already be renamed and metadata may have been transferred. Error 1176 is the rename failure whose outcome hinges on whether a backup name was requested.

Example

A configuration service calls ReplaceFile without a backup parameter. The target is removed, but an endpoint-protection filter prevents the candidate from taking the target name, producing 1176. Recovery finds no target but a valid flushed candidate, preserves it, records the conflict, and completes the rename after the filter releases the directory.

References

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