Sync troubleshooting
Ad Marginem syncs your library across devices via an eventual-consistency engine: each client writes locally, queues operations to the sync log, then push/pulls against the server when the network is available.
How to tell sync is working
- Settings → Sync shows the last sync time, the queue depth, and a per-device “pending operations” count.
- The cloud icon in the bottom-right of the main window goes green when the queue is empty; yellow when push is in flight; red on failure (with a tooltip).
Conflicts
When two devices change the same field of the same paper while offline, the engine surfaces a conflict drawer at the top of the main window. Each row shows the field name, your local value, the server value, and three buttons: Keep mine / Take server / Inspect. Inspect opens a side-by-side diff. No silent overwrites.
Diagnosing failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Cloud icon stays yellow > 30s | Slow upload (large PDF in the queue) | Wait, or pause sync until the upload finishes. |
| Cloud icon goes red, tooltip says “Unauthorized” | Session cookie expired | Sign in again — Settings → Account → Sign in. |
| Cloud icon goes red, tooltip says “Network” | Offline or DNS issue | Check connectivity; the queue keeps pending and retries automatically. |
| Conflicts keep appearing for the same paper | Two devices both editing live | Pick one as canonical for the duration; the other resumes editing after you resolve. |
Resetting a device
If sync gets wedged on one device only, Settings → Sync → Reset this device clears the local sync state without touching the server. The next sync pulls everything fresh. Local-only annotations that haven’t pushed yet are lost — Ad Marginem prompts before doing this.
Reporting a sync bug
File an issue at the GitHub tracker with: your platform, your client version (Settings → About), and the sync log lines from the moment the failure started (Settings → Sync → Export log).