Skip to content

Commit 839a6d4

Browse files
authored
users: Troubleshooting for "folder marker missing" error messages (#798)
Primary motivations are many forum threads over the years such as this one: https://forum.syncthing.net/t/the-problem-with-forum-support/20154 Also an old discussion: syncthing/syncthing#5207 Once/If this PR is merged, I would also like to link it from within the error message in syncthing, so that it can be found immediatly.
1 parent f9dd97c commit 839a6d4

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

users/faq-parts/troubleshooting.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,3 +157,38 @@ are run by volunteers all over the world. They usually listen on ports 443 or
157157
address you are concerned about with `the current list of active relays
158158
<https://relays.syncthing.net>`__. Relays do not and can not see the data
159159
transmitted via them.
160+
161+
I am seeing the error message "folder marker missing". What do I do?
162+
--------------------------------------------------------------------
163+
164+
Syncthing uses a specific marker usually called ``.stfolder`` to determine whether
165+
a folder is healthy. This is a safety check to ensure that your folder is properly
166+
readable and present on disk. For example, if you remove a USB drive from your computer
167+
or unmount a filesystem, then syncthing must know whether you have really deleted **all** of
168+
your files. Therefore, syncthing always checks that the ``.stfolder`` is present.
169+
170+
When this error appears, syncthing assumes that the folder has encountered some type of error
171+
and will stop syncing it until the ``.stfolder`` reappears. Once that happens, all changes made
172+
to the folder locally will be synced (i.e. missing files will be considered deletions).
173+
174+
- If you get this error message, check the folder in question on your storage. If you have
175+
unmounted the folder (or a parent of it), you must remount it for syncthing to resume syncing
176+
this folder.
177+
178+
- If you have moved the folder, you must either move it back to its original location, or remove the
179+
folder from within the syncthing UI and re-add it at its new location.
180+
181+
- If the folder is present on disk, with all of its children files and directories, but the ``.stfolder``
182+
is still missing:
183+
184+
It is possible that a file cleaning software has removed the ``.stfolder``. Some software
185+
removes empty folders, and the ``.stfolder`` is often empty. This happens particularly often on Android.
186+
To remediate, recreate the ``.stfolder`` and add a dummy file in it, or add an exception to your
187+
cleaning software.
188+
189+
If you are still unsure what has happened, you can remove the folder from within the syncthing UI and re-add it
190+
at the same location. This causes syncthing to attempt an automatic re-creation of the ``.stfolder``. Next,
191+
it will also reset the database state of this folder. It will be considered a "new" folder, meaning that its files
192+
will be merged with files from remote devices.
193+
194+
Also see the :ref:`marker FAQ <marker-faq>` for more information about the folder marker.

0 commit comments

Comments
 (0)