Troubleshooting

Do not clear a problem by deleting state, objects, hub data, staging, or recovery. The retained evidence is what makes safe retry and diagnosis possible.

First checks

codefoldersync doctor
codefoldersync status
codefoldersync service status
codefoldersync service logs

Status is offline

Confirm the hub path, SSH host access, remote installation, and available disk space. Local changes remain in the durable outbox. Restore connectivity and let the same events retry; do not create replacement events to work around an unknown network outcome.

Status is inconclusive

The peer could not prove a filesystem, object, Git, protocol, scan, or apply invariant. Stop writers if the cause involves corruption, disk capacity, or unsafe paths. Preserve both hub and peer copies, fix the underlying condition, then run a normal sync and full verification.

Status is conflict

Synchronization completed and preserved all stable versions. Find ordinary siblings directly or inspect Git records:

codefoldersync conflicts
codefoldersync history
find /path/to/code -name '*CODEFOLDERSYNC-CONFLICT*'

Follow Conflicts and recoverybefore choosing or combining versions.

A mutating command refuses to run

The daemon is the only allowed writer for its configured folder. Stop the service for deliberate foreground maintenance, run the command, then start the service again. A second daemon also fails closed. Stale locks are moved to recovery on safe startup.

A join destination is rejected

A new peer must use an empty destination. Existing untracked content has no causal baseline, so Code Folder Sync refuses to guess whether it is an import, a partial join, or competing work. Move that content aside, join cleanly, then reintroduce deliberate changes through normal files.