docs/help/contents/sync/troubleshooting-sync.md
Work through this page in order. Nearly every sync problem is one of four things: the other device has not synced, sync is switched off somewhere, your email is not confirmed, or a note is stuck as conflicted. Forcing a push or pull is the last resort, not the first.
Check these in order — the first three cover most cases.
{{syncNow}} on mobile.{{settings}} and check the email address shown on each device.{{syncOff}}. A note with a crossed-out sync icon in the list has been deliberately excluded from sync, and turning that on deletes it from your other devices. Open the note's menu and toggle {{syncOff}} back off to bring it back into sync.Conflicted group and blocks sync until you resolve it.If all five check out and the note is still missing on the other device only, a force push from the device that has the note is the tool for it — read the warning there first.
There are two different causes, and the icon tells you which:
Both show the same tooltip, Sync disabled — the icon is what distinguishes them:
{{disableSync}} in {{settings}} → {{account}} → {{sync}}. Turn that switch back off.{{emailNotConfirmed}} next to your account dot; click it to confirm your email.::: info If you already confirmed your email Occasionally the server still thinks an already-confirmed address is unconfirmed. Notesnook detects this during sync and refreshes your login token automatically, so the next sync attempt fixes it. If it doesn't, log out and back in.
:::
Sync only runs while you are logged in. On mobile, tapping the profile button at the top of the side menu opens a sheet that reads {{notLoggedIn}} when you are not; on desktop and web the account dot and sync icon disappear from the status bar.
If you were logged in and got signed out, your session expired. Log in again — your notes are still on the device, and nothing needs re-downloading. If you see Unauthorized. or User encryption keys not generated. Please relogin., that is the same thing: log out and log back in.
::: warning Do not delete the app to fix a login problem Notes that were never uploaded live only on that device. Reinstalling deletes them. Log out and back in from inside the app instead, and take a backup first.
:::
The server refused the request because too many arrived from your account in a short window. It is temporary and nothing is lost.
Stop pressing sync, wait a few minutes, and let the app sync on its own. If you have been repeatedly running {{forcePullChanges}} or {{forcePushChanges}}, that is the usual cause — those transfer your whole dataset every time and are not meant to be used routinely.
{{syncFailed}} means the last run did not complete. The error message in the toast tells you which stage failed:
| Message | What it means | What to do |
|---|---|---|
(no message — only the status flips to {{syncFailed}}) | The app could not open a connection to the sync server within 30 seconds. Connection failures are written to the log as Could not connect to the Sync server. Please try again. but are deliberately not shown as a toast. | Check your connection, then sync again. Behind a strict firewall or VPN, try another network. |
Notesnook Sync Server is not responding. Please check your internet connection. (the full message goes on to give a support address and a reference error) | The server did not answer at all. Other names you may see are Authentication Server, Eventing Server and Monograph Server. If you have pointed the app at your own servers you get the raw network error instead of this friendly one. | Check your connection. |
You are being rate limited. | Too many requests. | Wait a few minutes. |
Unauthorized. | Your session is no longer valid. | Log out and log back in. |
Failed to send all items. Sent X out of Y. | The upload stopped partway. | Sync again — the remaining items are still queued and go out on the next run. |
A failed sync never loses local data. Everything you wrote is on the device and goes out on the next successful run.
A conflicted note stays conflicted until you pick a version — Notesnook will not choose for you, and it will not merge two versions of your text together. Until it is resolved, the desktop status bar keeps showing a red alert icon whose tooltip reads Merge conflicts
Notes.Conflicted group at the top of the list.{{saveACopy}} to keep both.If a note re-conflicts every time you sync, the two devices are each holding an edit the other has not seen. Resolve it on one device, let that device sync fully to completion, then sync the other one.
Full instructions, including what the highlighted diff means, are in what are merge conflicts?.
Attachments sync separately from note text. A note can arrive on a device while its images are still on the server.
{{fileCheck}} on the affected files — it verifies the file actually exists on the server and is intact.{{settings}} → {{profile}}.{{attachments}} — "Manage attachments" — press {{open}}.{{fileCheck}}.Match the direction to the symptom, and take a backup first.
| Symptom | Use | Effect |
|---|---|---|
| Changes made on this device are not appearing on other devices | {{forcePushChanges}} | Overwrites the data on the server with the data from this device |
| Changes from other devices are not appearing on this device | {{forcePullChanges}} | Overwrites the data on this device with the latest data from the server |
::: danger Both of these overwrite data The app's own warning: "This must only be used for troubleshooting. Using this regularly for sync is not recommended and will lead to unexpected data loss and other issues." Anything that exists only on the side being overwritten is lost, and Notesnook cannot recover it for you. Never run both in sequence, and never use them as a routine "sync harder" button.
:::
Both buttons and the exact steps are documented in sync settings.
Send the details to [email protected] — which devices, what the status indicator says on each, and the exact error text.