This thread revisits the long-standing “Unexpected Items” issue in Receive-Only folders, where a locally missing file can permanently stall synchronization. I aim to move past philosophical debates by framing the problem through first principles and proposing a concrete, user-centric solution.
Core Observations:
Definition of Synchronization: A sync tool exists to reconcile a destination with a source according to configured rules (folder type, permissions, conflict handling), ensuring the intended state is reflected at the destination.
Valid Safety Principle: “Never overwrite existing user data” is crucial when a local file exists. It prevents data loss and aligns with expected Receive-Only behavior.
Category Error in Application: Applying the overwrite principle to a missing file is a logical misapplication. If a file is absent locally, there is nothing to overwrite, and thus no risk. Blocking sync here treats absence as a local file modification, which is inconsistent with the principle.
Contradiction on Intent: Halting restoration implicitly interprets absence as intentional. While the developers avoid speculating on why a file is missing, stopping sync itself is an action based on assumed intent. This creates a contradiction: claiming intent-neutrality while making a blocking decision that only makes sense if intent is assumed.
Practical Result: Users face an “Unexpected Items”, etc. errors with no in-GUI resolution. Workarounds via SSH, CLI, or folder recreation are required. This is not a philosophical safety gain - it is a broken workflow that prevents the tool from performing its core function.
Proposal: Grant Explicit User Agency
The goal is not to rehash intent debates but to provide practical resolution paths.
I would suggest:
A prominent “Restore Missing Files” button in the GUI when such errors occur (the prior versions had similar buttons but for different conditions/states, so this aligns well).
A configurable folder policy toggle (e.g., “Automatically restore missing files”).
Clear user choice prompts during exceptional states.
Empowers Users: Those who want convergence can act deliberately, without CLI workarounds.
Restores Fundamental Functionality: The tool no longer stalls due to missing files, and synchronization proceeds predictably.
By reframing the issue as a design and UX problem rather than a philosophical impasse, this solution balances safety, user control, and the core purpose of synchronization.
Assuming the receive system is connected to a system with the source file, this file could be replaced within seconds of being deleted.
I think there is some value in what you’re suggesting but I do tend to think effort needs to be on why the receive folder is changing.
in our situation we set syncthing permissions up to be able to write into the receive only folders, and blocked general users from having write access. So if they try to modify or delete files in receive only folders they get permissions errors immediately. This way they know immediately they did something wrong and they know they shouldn’t be writing. It also allows syncthing to update the file because it’s never out of sync, and the user isn’t confused by a file they just deleted reappearing seconds later.
I think this really comes down to separating two different concerns.
Filesystem permissions and user discipline are preventive measures.
Synchronization, on the other hand, needs a clear recovery path when prevention fails for any reason.
Receive-Only already defines where authority lives. From that standpoint, a file disappearing on the receiver, regardless of how or why, isn’t a meaningful state change in itself, it’s just a divergence from the authoritative model.
Right now, Syncthing tends to treat that divergence as something to preserve indefinitely, which is what leads to the deadlock. Offering an explicit, in-GUI way to restore the authoritative state wouldn’t weaken safety - it would simply allow the synchronizer to do its job when external factors get in the way.
That approach keeps prevention optional, makes recovery explicit, and keeps responsibilities clearly separated.
A deleted/missing file in a receive-only folder leads to a revert button being present in the UI, i.e. this is recoverable in the UI. From memory the list isn’t called “Unexpected Items” but “Locally modified items”, but that seems like a case of potato potato to me. So not quite sure what you mean here?
The other part where you propose to automatically resolve locally removed files in a receive-only folder seems sensible, at least not a non-starter: Contrary to the usual requests to auto-resolve local modifications, it doesn’t delete any data. And the benefit is that there’s no action (UI or otherwise) needed by the user to get back in sync. I am still not entirely sure I am convinced it’s a good idea, as imo it’s also useful to be consistent in that explicit user action (file deletion) needs an explicit user action to undo. At the same time we do something similar with conflicts, so maybe one can even contruct some consistency there
Isn’t that exactly what’s implemented? Open the GUI, click the button, and everything is restored.
And before, if you want to know what was changed, you can view the list of changes that will be reverted when you click the button.
