Recover from a failed or blocked sync

Find the message you see, fix its cause, and bring a Follower Machine back to Convergence without losing changes made on it.

Find the message or exit code you see in the tables below and follow its fix. When the fix is done, canonfig sync --apply reports Converged.

Before you start

Collect the state of the Follower Machine:

canonfig status
canonfig doctor --no-input

status shows the recorded Synchronization Run and any resource that is blocked. doctor checks this machine; see Doctor probes and exit codes.

Keep the evidence

Do not delete Canonfig's database, cache, or run journal to clear an error. canonfig recover uses those records to restore your files.

What a failed run leaves behind

An apply failure (exit 7) rolls back. Canonfig restores every file, directory, and config it changed in that run, then names the resource and the cause.
Human Action Required (exit 3) and Follower Drift (exit 4) stop the run without rolling back. Resources applied before the blocked one stay applied, the blocked resource is unchanged, and later resources are skipped. canonfig sync --plan lists the blocked resource as human-action or drift-conflict.
Tool installs are never rolled back. A package an installer installed stays installed, and the next run finds it in place.

After you fix the cause, canonfig sync --apply applies everything that was rolled back or skipped.

Finish an interrupted run

A run that stopped during apply (a crash, a killed process, a reboot, or a full disk) stays open. status shows which actions finished, and the next sync stops with exit 4.

Run:
```
canonfig recover
```
recover finishes or rolls back the open run from its journal and removes Canonfig's temporary files (.cf-<12 hex>.tmp) next to its targets. It restores the file permissions it recorded before the run: POSIX modes on Linux and macOS, and owner, group, and access rules on Windows. It does not restore Windows audit rules.
Run canonfig sync --apply.

Close a run that cannot be recovered

Use this when recover cannot finish the run, for example because its Profile Revision is not authorized for this Follower Machine, or the Follower Machine selects another Machine Profile.

abandon does not roll back

Whatever the run applied stays applied. The next sync treats it like any other state on the Follower Machine.

Run:
```
canonfig abandon
```
Run canonfig sync --apply.

status or sync --plan shows a resource as drift-conflict, and the sync exits 4. A file whose Apply Policy protects local edits changed on this Follower Machine since Canonfig last applied it: a skill (replace-if-unmodified), or the Source Machine's section of an append-local file. Canonfig keeps the local content and never merges or overwrites it. Files with the replace policy belong to the Source Machine; the next apply replaces local edits to them without reporting drift.

Decide which version to keep:

The Source Machine's version: move the local copy aside, then run canonfig sync --apply. Canonfig writes the missing target again.
Your local change, on every Follower Machine: copy it to the Source Machine, publish a Profile Revision there, then run canonfig sync --apply.
Your local change, on this Follower Machine only: for a config key, claim it as a Local Overlay, then run canonfig sync --apply:
```
canonfig overlay set claude-settings --target ~/.claude/settings.json --key permissions.defaultMode
```
Files and skills cannot become a Local Overlay.

Resolve Human Action Required

The sync exits 3 and the message names the step only you can take:

Cause	What the message gives you
A login that cannot finish without you	the command to log in
A locked or unreachable credential store	the store and the command to unlock it
A Follower Machine config file that does not parse	the file, line, and column
An agent policy that forbids a needed capability (elevation, restart, reboot)	the capability
An action that needs a decision under `deterministic-only`	the resource and the choice

Do not work around the message

Do not put a token on the command line, turn off certificate pinning, widen an allowlist to your whole home directory, or switch to agent-apply to clear the outcome.

Do what the message says.

Check the machine and the plan:

canonfig doctor --no-input
canonfig sync --plan

Run canonfig sync --apply.

Messages by exit code

Exit 2: usage or configuration

Message	Cause	Fix
"source/follower version mismatch: source `<a>` vs follower `<b>`. install the same major.minor canonfig release on the Source Machine and on every follower"	The Source Machine and this Follower Machine run different `major.minor` releases.	Install one release line on every machine.
"this machine is not enrolled; run 'canonfig follower enroll' first"	The machine has no Follower Identity.	Enroll it with an invitation from the Source Machine.
"follower `<name>` has no run to recover"	You ran `canonfig recover` with no open run.	Run `canonfig sync --apply`.
"`<path>` needs N characters including Canonfig's staging names, but this machine accepts file paths of at most 260 characters because Windows long paths are not enabled"	A Windows target path is too long. Nothing was changed.	Shorten the target or enable long paths; see Windows path length.

Exit 3: Human Action Required

Message	Cause	Fix
"`<path>` changed after run `<run>` was interrupted: the current content matches neither the content before the run nor what the run was writing, so recovery stopped without changing anything."	Someone edited a target after the run stopped. Canonfig keeps the file and its copy from before the run.	Save your edit elsewhere or restore one of the two versions, then run `canonfig recover` again. To keep the files exactly as they are, run `canonfig abandon`.
"this machine's credential store could not return the follower credential, so no Source request was made: ..."	The keyring or Keychain is locked, or this session cannot reach it. The Follower Identity is not revoked.	Unlock the store in this session. For scheduled runs, see Run Canonfig unattended.
Any other step only a person can take	See Resolve Human Action Required.	Do what the message says, then sync again.

Exit 4: conflict or drift

Message	Cause	Fix
"follower `<name>` has a run still open; run 'canonfig recover' first, or 'canonfig abandon' to close it without rollback when it cannot be recovered"	A run was interrupted.	Finish an interrupted run.
"run `<run>` was created by canonfig `<version>` ...; finish the run with the creating build or set CANONFIG_ACCEPT_FOREIGN_BUILD=1 to accept the upgrade"	You upgraded Canonfig while a run was open.	Reinstall the version the message names, run `canonfig recover`, then upgrade. Set `CANONFIG_ACCEPT_FOREIGN_BUILD=1` only if you accept that the upgraded build recovers a run it did not create.
"another canonfig process (PID 48211) has been running 'sync --apply' for this follower since `<time>`; wait for it to finish, then retry. If PID 48211 is not a canonfig process, delete `<lock path>` and retry"	`sync --apply`, `recover`, and `abandon` run one at a time. Canonfig takes over a lock whose process has exited.	Wait for the other run to finish, for example a scheduled run. See the warning below before you delete the lock.
A resource shows `drift-conflict`	Follower Drift.	Resolve Follower Drift.

Check the PID before you delete the lock

Delete the lock file only if that PID is not a Canonfig process. Removing the lock of a live run lets two runs change the same files.

Exit 5: authentication or revocation

Message	Cause	Fix
"this follower's credential has been revoked"	The Source Machine revoked this Follower Identity.	Ask for an invitation on the Source Machine and enroll again.
"the follower credential is invalid"	The Source Machine does not accept this credential.	Enroll again with another invitation.
"the invitation has expired; ask the Source Machine for a new one"	The invitation passed its `--expires` time.	Create another invitation on the Source Machine.
"the invitation was already used; ask the Source Machine for a new one"	Each invitation enrolls one machine once.	Create another invitation on the Source Machine.
"source TLS pin validation failed" (from `doctor`)	The Source Machine's certificate does not match the one this Follower Machine pinned. Canonfig never resets trust on its own.	Enroll again with another invitation.

Exit 6: Source Machine unreachable

Message	Cause	Fix
"nothing answered at the Source endpoint `<host>` (ECONNREFUSED)"	The Source Machine is not serving, or the managed tunnel is down.	Start the Source Machine's service, or run `canonfig tunnel start` if you reach it through the managed tunnel.
"the Source is unreachable because the managed tunnel `<endpoint>` is down" or "is stopped"	The managed tunnel is not running.	Run `canonfig tunnel start`.

For every tunnel and service message, see Run Canonfig unattended.

Exit 7: apply or verification failure

Message	Cause	Fix
"resource `<id>` could not be applied to `<target>`: `<cause>`", for example "resource claude-settings could not be applied to ~/.claude/settings.json: atomically write file failed: EACCES: permission denied"	An action failed. Canonfig rolled the run back.	Fix the cause it names, then run `canonfig sync --apply`.
"verification failed for resource `<id>`: ..." or "verification failed for agent task `<resource>`"	The actions ran, but the resource does not pass its `verify` check.	Fix the cause the message names, then run `canonfig sync --apply`. For tools, see How Canonfig installs and verifies tools.
"the filesystem holding `<path>` needs N bytes (M MiB) free but only N bytes (M MiB) are available; nothing was changed. Free space there, then retry"	Canonfig checks free space before it records a run and before it downloads content. No run was opened, so there is nothing to recover.	Free space on that filesystem, then run `canonfig sync --apply`.
"restore Windows permissions failed on `<path>`" (during `canonfig recover`)	Windows refused to restore an owner or access rule Canonfig recorded. The run stays failed, and the journal and backups stay in place.	Fix the permission problem on that path, then run `canonfig recover` again.

Recover from a failed or blocked sync

On this page