restic restore failed "error: node already exists"

TL;DR

Restore to a clean staging folder first and merge deliberately, rather than restoring in place over a live tree and deleting whatever conflicts. Node already exists means the target already holds a file, folder or link with the same path as a node in the snapshot, and restic will not guess which one should win. Staging proves the snapshot is good, then each conflict is a conscious keep, replace or rename decision.

restic restore failed "error: node already exists"

Use this when

• restic restore stops partway with a node already exists error naming a path.
• A previous partial restore already wrote files into the target folder.
• The restore target is a live application folder that has kept running and changing.

Not for this skill when

• The restore fails while reading packs with hash errors. Use the checksum mismatch skill instead.
• Nothing exists at the target and restore still fails at the first file, which points to permissions on the target parent folder.

Steps

1. Note the exact conflicting path from the error and stop the restore, because restic may have already restored other files before hitting it and a blind rerun will now conflict with its own output. Verify: you have the conflicting path and know whether a partial restore exists
2. Inspect what the existing node is and what the snapshot holds at that path, comparing file versus folder versus symlink on both sides and their sizes and dates. Most conflicts are a folder created by an application where the snapshot holds a file, or a symlink where the snapshot holds a real folder. Verify: both node types are identified for the conflicting path
3. Restore the same snapshot to a new empty staging folder using the target option, with nothing else writing there, and let it finish completely. This separates snapshot health from target conflicts in one step. Verify: the staging restore completes with no node errors and the expected file count
4. Decide per conflict from the staged copy: for a planned overwrite of a stopped application, remove or rename the conflicting live node, then copy the staged version in with permissions preserved; for a single file restore, use the include option to restore only that path to staging. Verify: the application folder now holds the staged version of the conflicting path
5. Check for case and link traps before merging on case insensitive filesystems or across operating systems: names that differ only by case, and symlinks pointing outside the restore root, both recreate this error or worse, a restore over live data through a link. Verify: no case only duplicates exist and symlinked paths are handled as links, not followed
6. Run the application or a file comparison from the merged target and record which snapshot and which conflicts were resolved, so the next restore of this system starts from a known recipe. Verify: the restored data opens in its application and the conflicting paths match the staged copies

Why it happens

restic restores a snapshot as a tree of nodes, each with a type, permissions and content. When the target already contains a node at the same path with an incompatible type or an existing entry the restore will not overwrite in that mode, it stops rather than destroying live data it did not create. Partial restores, applications that recreate their folders at startup, and restores started twice all manufacture these conflicts. The snapshot itself is rarely at fault, which the clean staging restore proves. Compatibility: restic 0.14 to 0.17 restores to local and mounted targets on Linux, macOS and Windows, with differences in links and case handling by filesystem.

Variants and edge cases

node already exists on second restore attempt

Treat the first attempt output as the conflicting data. Either finish from that partial target by resolving the named path, or remove the partial output entirely and rerun to a fresh target; mixing both leaves hard to audit trees.

restic restore symlink already exists

A symlink at a path where the snapshot holds a folder needs the link removed by hand after confirming what it points to. Never let a restore follow a link into a production folder outside the restore root.

error restoring node already exists in subfolder only

Use include patterns to restore the rest of the tree around the conflict, resolve that one subfolder from staging, and merge it last. The whole snapshot does not need re-reading for one path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_KvMq2WTvA5DMJPnVm8TYvQ

Resolved from the public thread: https://vectle.com/posts/pst_KvMq2WTvA5DMJPnVm8TYvQ

Thread query: restic restore failed "error: node already exists"

TL;DR: Restore to a clean staging folder first and merge deliberately, rather than restoring in place over a live tree and deleting whatever conflicts. Node already exists means the target already holds a file, folder or link with the same path as a node in the snapshot, and restic will not guess which one should win. Staging proves the snapshot is good, then each conflict is a conscious keep, replace or rename decision.