Syncthing "folder marker missing": how to restart the folder without deleting files

Syncthing stopped the folder because it cannot find .stfolder in the folder's root. Its FAQ names three causes: the disk or network share is not mounted, the folder moved, or cleanup software deleted the marker. So look inside the folder before you touch anything:

ls -la /path/to/folder | head
find /path/to/folder -type f | wc -l

• Empty: the drive is not mounted, or the path is wrong. Mount it, then press Rescan on the folder.
• Some files missing: leave the marker alone. Remove the folder in Syncthing and add it again at the same path, so the missing files download again.
• Every file is there, only .stfolder is gone: something deleted the marker. Run mkdir .stfolder in the folder, put a small file inside, then press Rescan.

Never create .stfolder in an empty or half-empty folder. Syncthing would read every missing file as a deletion and send it to every other device. In our lab that emptied the other device's copy of 200 files in about two seconds.

The terms this answer turns on#

A folder marker is a small item Syncthing keeps in the root of every synced folder. Its default name is .stfolder. In version 2.1.7 it is a directory holding one text file that reads "This directory is a Syncthing folder marker. Do not delete." Syncthing checks that the marker exists before every scan and every sync. If it is missing, the folder goes into an error state: Syncthing stops scanning and syncing it, and the other devices carry on without it.

Syncthing also keeps a database of every file the folder held, the "Local State" in the web UI. A scan compares the disk with that database. A file that is in the database but not on disk counts as deleted, and the deletion goes to every device sharing the folder. This is why the marker exists. Syncthing's FAQ gives the example of a removed USB drive: Syncthing "must know whether you have really deleted all of your files."

File versioning is a per-folder setting. When a change from another device deletes or replaces a file, Syncthing moves the old copy into .stversions instead of throwing it away. It is off by default.

Two answers circulate, and one of them deletes your files#

"Just recreate .stfolder." This is right only when the files are all there. On the forum thread "Folder marker missing, re-created it -- file mass deletion!", a user copied a .stfolder in from another folder. A minute later the other computer was deleting thousands of files. Their local folder had been emptied by something else, and the marker told Syncthing the empty folder was real. The FAQ says it plainly: once the marker reappears, "missing files will be considered deletions".

"Remove the folder and add it again." This is the FAQ's fallback when you are unsure. It is safe for the other devices, because removing the folder clears its database. The re-added folder starts as new, and its files "will be merged with files from remote devices". The cost is on your side. Anything you deleted locally while the folder was stopped comes back. And if the disk is not mounted, Syncthing downloads the whole folder into the empty mount point.

What the code checks, and when#

The error text lives in lib/config/folderconfiguration.go: "folder marker missing (this indicates potential data loss, search docs/forum to get information about how to proceed)". The check first looks for the folder path. Then it looks for an item with the marker name inside it. A file or a folder both pass. The name is the folder's markerName setting, .stfolder unless you change it.

Syncthing creates the marker in only one case. model.go calls CreateMarker when a folder has no history in the database, which means the first start after you add it. It makes the default .stfolder directory with a file inside, to reduce "the risk of the marker directory being removed by automated cleanup tools". It never makes a custom marker. Once the folder has synced anything, it never recreates .stfolder on its own.

Removing a folder from Syncthing removes its marker too. If .stfolder holds anything besides its own file, Syncthing renames it .stfolder.removed- plus a time stamp. Issue 6106 reported that this broke a second folder pointing at the same path, on v1.3.0. Current code skips the removal when another folder still uses that path.

The check runs at the start of each scan and each sync. It does not run on its own timer. With the default rescan interval of 3,600 seconds, folder.go picks the next scan at random between 3/4 and 5/4 of it, so 45 to 75 minutes. The error can therefore appear long after the disk went away. A change arriving from another device brings it sooner.

A worked case: the USB disk that came up late#

Take a Raspberry Pi running Syncthing in Docker. The folder "Photos" lives at /mnt/usb/photos on a USB disk, and a laptop shares it. After a power cut, the web UI on the Pi shows "folder marker missing".

Start on the Pi with ls -la /mnt/usb/photos. Suppose it prints only . and .., and findmnt /mnt/usb prints nothing. The disk did not mount. The photos are still on the disk. The laptop is untouched, because the Pi stopped the folder before sending anything.

Now mount the disk and list the folder again. You should see the photos and .stfolder beside them. Restart the Syncthing container, because with Docker's default bind settings a container started before the mount does not see it; Why a container writes to the empty folder when the drive is not mounted explains why. The folder comes back clean. Our lab cleared the same state with Rescan and changed no files.

Suppose instead you had typed mkdir .stfolder while the folder was empty. The next scan would find 0 files where the database lists thousands. The Pi would announce them all as deleted, and the laptop would delete them. Our lab did exactly this with 200 files.

What we measured#

Two containers ran syncthing/syncthing v2.1.7 (built 20 October 2026) on Docker Engine 28.1.1 with kernel 5.4. Device A held the folder on a 100 MB ext4 disk image on a loop device, so unmounting it is unplugging a disk. The folder held 200 small files in 20 directories. Device B held a normal copy. Folders used the defaults: send and receive, watcher on, rescan every 3,600 seconds, no versioning unless stated.

After the mass deletion we mounted A's real disk again. A rescanned, found its 200 files, and B downloaded them all back. That worked only because the files still sat on A's disk. In the forum thread they did not.

Two results are worth knowing. The web UI's Local State kept saying 200 files while the disk was empty, because it shows the database, not the disk. And the marker error did not appear the moment the disk went. It waited for the next scan or incoming change.

Which fix for which folder#

The moved-folder row is the FAQ's advice. If the old path is gone completely, Syncthing reports "folder path missing" instead. In Docker it usually is not gone. docker run -v and Compose recreate a missing bind source as an empty folder, as Why a container gets permission denied on a bind mount measured. That empty folder gives the marker error. The FAQ also covers cleanup software, saying it "happens particularly often on Android", and suggests adding an exception for .stfolder.

Recreating the marker when the files are all there#

Compare counts first. In the web UI, open the folder and read the file count under Global State. That is what the other devices hold. Then count the disk:

cd /path/to/folder
find . -type f -not -path './.st*' | wc -l

If the two are close, recreate the marker as the user Syncthing runs as. The FAQ asks for "a dummy file" inside, so cleanup tools do not treat it as an empty folder:

mkdir .stfolder
echo "Syncthing folder marker. Do not delete." > .stfolder/keep.txt

In the official Docker image Syncthing runs as UID 1000 by default, so docker exec -u 1000 syncthing mkdir /var/syncthing/Photos/.stfolder does the same from the host. Then press Rescan, or call the API with the key from Settings:

curl -X POST -H "X-API-Key: YOUR_KEY" "http://127.0.0.1:8384/rest/db/scan?folder=FOLDER_ID"

If the counts are far apart, stop. Remove the folder in Syncthing and add it again at the same path instead. That downloads what is missing rather than deleting it elsewhere.

Read-only folders and custom markers#

On a read-only mount, Syncthing cannot create .stfolder, so a new folder fails at once. The FAQ's fix is the Marker Name setting, under Actions, Advanced, Folders. Point it at a file or folder you know is always there. Syncthing will not create a custom marker, so it must already exist. Pick something that lives only on that disk, so the check still fails when the disk is missing.

A synced disk that turns read-only later gives a different error. The marker is still there. Instead each changed file fails with read-only file system, and Syncthing retries after a minute, then backs off. Fix the disk, and the queue clears on the next retry.

Stop it happening again#

Make Docker wait for the disk. A RequiresMountsFor= drop-in for docker.service and chattr +i on the empty mount point are both covered in Why a container writes to the empty folder when the drive is not mounted. In our lab chattr +i also stopped Syncthing from creating a marker in the empty mount point.

Turn on file versioning on the devices that would receive a mass deletion. Trash Can versioning kept every file our lab deleted. A receive-only folder did not: the docs say it applies "all changes from the cluster". The ignoreDelete setting exists, but the docs say enabling it "is highly discouraged".

Versioning is not a backup. The thread's user had versioning on, then reported the Restore Versions screen still sitting after an hour on thousands of files. Syncthing vs Nextcloud explains why Syncthing alone is not a backup, and Backups that actually restore covers the copy Syncthing cannot reach.

When this answer stops applying#

We tested Syncthing v2.1.7 on Linux in Docker, with a local ext4 disk. Android, Windows, NAS packages and network shares were not tested. On Android the FAQ says marker deletion by cleanup software happens "particularly often". Encrypted receive folders were not tested. The code we read is the v2.1.7 tag. If files were already deleted before you saw the error, this page cannot bring them back. Only versioning or a backup can. Watcher limits are a separate problem with a separate error, covered in What fs.inotify.max_user_watches should be for Docker apps.

What to do next#

Run ls -la on the folder before anything else. Then follow the row in the table above that matches. Once it is syncing again, turn on versioning on the other devices and add the mount guard, so a late disk becomes a harmless error next time.