When Sync Goes Wrong

Syncthing rarely fails loudly; it does the wrong quiet thing, exactly as configured, until somebody notices. This chapter is the symptom list — each entry something the lab either caused on purpose or saw in the captures, and each with the same shape: what it looks like, what it almost always is, and the check that tells you.

The file never arrived

A file exists on one device and, minutes later, does not exist on the other, with no error anywhere.

Check the gauges first. /rest/db/status for the folder (chapter 9): if the sending side shows the file in localFiles but the pair's numbers never move, the devices are not talking — check /rest/system/connections. If the numbers settled and agree without the file, the file was never a sync candidate at all: the two standing causes are an ignore pattern matching its name (chapter 5 — rest/db/ignores shows the lines; remember patterns are per-device and the shared list only travels via the include trick) and a folder type doing its job — a send-only device's counterpart file, or anything at all created on a receive-only device (chapter 8: was it created on the wrong side?).

And check pause. A paused folder holds everything, silently, by design (chapter 9's late addition sat out its eight seconds). Half of troubleshooting Syncthing is discovering which sensible setting from last month is still, sensibly, on.

The edit came back

You fixed the file; an hour later the old text is back. Nothing "restored" it. While your device was offline, disconnected, or merely slower, another device edited — or re-saved — its copy with a newer modification time, and when the two met, chapter 7's rule ran: newer wins the name, and your version, if you are lucky, is sitting beside it with a .sync-conflict name. If there is no conflict copy, look at versioning on the receiving side (chapter 6): the overwritten generation is in .stversions on the device whose copy was replaced — which, for the "came back" symptom, is the machine in front of you.

The delete came back

The reverse haunting: a file you deleted returns. First, what it is not: a device that was merely switched off when you deleted the file does not bring it back. Changes carry version records, its untouched copy is simply out of date, and when it reconnects the deletion reaches it and its copy is deleted too.

Resurrection takes a stronger claim than "still here." The standing one is a change: while the devices were apart, something on the other device modified the file — and chapter 7's documented rule is that edit beats delete, so the file returns, edited, and your deletion is what gets undone. The other classic is a device rejoining with a fresh database (reinstalled, index reset): everything on its disk announces itself as new, deletions it never recorded included. The check is the same for both — get every device connected (/rest/system/connections), let the folder settle, and ask which device re-introduced the file and what state it was in. And if the file keeps returning across settled, connected devices, something on one machine is recreating it (an editor's backup, a build step), and Syncthing is faithfully syncing the resurrection.

The folder will not settle

state stuck at syncing or scanning, or needFiles never reaching zero. Read the two numbers separately. needFiles > 0 with a connected peer is usually a file changing under the transfer — a log being appended, a database being written — so each completed download is already stale; the cure is ignoring it (chapter 5) or accepting it. needFiles > 0 with no connection is chapter 2's world: pairing, addresses, discovery. And a folder stopped dead with an error about the folder marker is the .stfolder from chapter 3 doing its protective job — the directory Syncthing found is not the directory it left (unmounted drive, wrong mount, restored-from-backup path); fix the mount, not Syncthing.

Many conflict files

A folder accumulating .sync-conflict copies is not malfunctioning; it is a workflow report. Two devices edit the same files while apart, regularly. Chapter 7's machinery keeps both versions every time, forever, until a human merges them. The lasting fixes are human too: one editor per document, or the document split so the editors stop meeting.

Two artefacts that are not problems

Seen in the lab's own final listing, so they don't alarm you in yours:

share-a/.syncthing.front-page.md.tmp
share-b/.stversions/issue-12-draft.md

Incoming files are staged under a .syncthing.<name>.tmp name and renamed into place when complete; one orphaned temp file is the residue of a transfer interrupted at the wrong moment (the lab's was left by the conflict pull of chapter 7) and can be deleted when no sync is running. And .stversions is chapter 6's archive, present exactly when versioning is doing what you asked.

The general shape

Work the list in the guide's own order: connections (are they talking?), status (do the counts agree, and what do the gauges implicate?), types and ignores (is it configured to do exactly this?), and only then the exotic. Syncthing's supreme troubleshooting virtue is that its state is inspectable — every number the GUI shows is one curl away — and its supreme trap is the same as its design: there is no server keeping a second opinion. The devices in front of you are the whole truth, so learn to ask them.