I originally posted this on my blog but I felt like I should have posted it here in the first place. Also, as these get added to the help site or fixed, I will be removing them from this post. I plan to keep this post as updated as possible.
Obsidian Vault & Sync Setup
First, if you aren’t aware, I want to go over how your Obsidian vault is set up and how Obsidian Sync works. There is a common misunderstanding for how Obsidian sets up your vault and how Obsidian Sync works. This factors into common problems.
Also, people not paying attention to Obsidian Sync’s limitations and attempting to use it anyway, could lead to some common problems.
Obsidian Vault Setup
Your vault is pretty simple, it is a folder with files in it. Obsidian runs by keeping a folder called .obsidian inside of your vault folder. That .obsidian folder stores the community themes and plugins you have installed, what you have enabled, the official plugin status as well as any other Obsidian settings.
Obsidian Sync Setup
Obsidian Sync connects to your local vault, encrypts the data, and copies it to Obsidian’s servers in its encrypted state. This means that the Obsidian Team does not have access to any of your folders or files inside your vault. They can simply see whether or not your vault exists. That’s it.
Once you connect Obsidian Sync to another device, this is the life cycle of your files inside your vault:
- Local Files on Device 1
- Copied to Obsidian Servers
- Copied again to Device 2
- Local Files on Device 2
Repeat steps 3 & 4 for all of your devices. While this copying can happen pretty quickly, it can cause issues, and that is where this article comes into play.
To get this set up, Obsidian’s Help Site has a perfect step-by-step guide on setting up Obsidian Sync on all of your devices.
Preface
This isn’t to say Obsidian Sync is not good. A lot of people are perfectly happy with using Obsidian Sync and may not run into any of these issues. These issues can happen though so it is important to be aware of them.
Pitfalls with Obsidian Sync
Clare Macrae went over these issues in detail on the Obsidian Discord Server earlier this year (February) and I plan to update this as things get updated and fixed.
Basically it comes down to this phrase, Sync is hard. She has been using Obsidian Sync for the last couple of years and documented issues she had while using it. This documentation was great and I want to make sure (with her permission) that this is easier to find because this documentation took a while to make and figure out ways around these pitfalls.
Day-to-Day Things
Editing Settings on one device can cause the loss of earlier edits made on another device.
This seems like a really bad sync glitch which can cause the loss of important files.
Sync icon is not visible at all times on mobile, so it’s easy to miss conflicts or not be aware that sync got disabled.
This can be fixed by using a CSS Snippet to show the icon at all times though it is not something built in.
Files get automatically deleted after adding code on Windows.
This is because Windows Defender is nuking the file, in most cases. Windows thinks it is a malicious PHP (or whatever code) script and deletes it. You can go to Defender settings and have it ignore the file.
I have been running Sync fine for a while but now all of a sudden my files are disappearing or the vault is running slow with only a few plugins.
There is one common issue that keeps happening that people seem to ignore on the Obsidian Help Site (link 2) (and in the Sync settings it warns you of this):
We do not recommend using a third-party sync service alongside Obsidian Sync. Using the same third-party service and Obsidian Sync on multiple devices can lead to conflicts, resulting in duplicate or corrupted files.
Cloud storage services like OneDrive and Dropbox offer “Files on-demand” or “Online-only files” features, which download files only when needed and remove them locally to save space. However, since these files are not always available locally, Obsidian Sync will interpret them as deleted, leading to their removal from your remote vault.
To avoid these issues, disable on-demand downloads when using Obsidian Sync with services like OneDrive or Dropbox. You will need to ensure that the third-party service settings are configured to always keep files on the device.
Very common issue on the Discord Server and Forum is that the Obsidian Vault starts acting up and being funky on their devices. A common issue is that people place their vault in the Documents Folder on Windows or iCloud Folder on Mac or people use iCloud on Windows and this is so prevalent that the mods decided to add a quick response to their bot that they use:
So, you have to make sure you disable Dropbox, OneDrive, iCloud, etc. where-ever you store your vault or store your vault on an external hard drive OR in your user directory that all the operating systems have.
You also have to remember something Obsidian Sync ≠ Obsidian Backup. This means Sync does not back up your files so you have to keep reliable backups. There are several ways to do this:
- Using Obsidian Sync + Obsidian Git as Obsidian Git contains a version history that persists between sessions and machines (below) and you can see the version history.
- Copying your Obsidian Vault to another folder that Dropbox, OneDrive or iCloud does touch. Just make sure you are not actively working on the vault located there. Also, make sure you do this regularly. If it is before exams, daily. If it is in the summer, weekly. That kind of thing.
- Using Obsidian Git instead of Obsidian Sync.
Syncing is taking a while; Is this normal?
Depending on the size of the files being synced, the number of files being synced, the type of files being synced and the number of community plugins and themes getting synced (if you have that enabled) can determine the length of time for your syncing.
Also, if you haven’t used the device in a while, that can take a while to sync.
Lastly, if you are syncing for the first time, that can take a while to sync.
Troubleshooting
Sync log is not persisted between sessions or between machines.
The log is very good for troubleshooting issues and making sure specific files got synced though these logs don’t stay when you close and reopen Obsidian and you can’t see Device 1’s logs on Device 2 and vice versa.
Dangers to be aware of
‘Obsidian needs to re-index your vault’ may mean that the location where your Obsidian Sync settings and passwords are stored has lost all its data.
This can happen if you store your vault in a 3rd party solution (discussed above) or if you force close Obsidian while it is syncing and don’t allow the syncing to finish (therefore corrupting files) or if Obsidian Sync deletes its own files (unlikely).
Deleting your .obsidian folder (for troubleshooting) or turning off the Sync plugin loses all of your Sync settings + the connection to the remote vault on the machine you are doing this on.
This means you have to set up everything all over again which can be a pain cause then you have to wait for the Sync to complete which, depending on the number of files you have and the size of those files, may take a while.
When copying a vault (such as moving the remote to a different region) sync settings are not copied.
Same as above.
Random edits made and lost, when turning back on syncing for a vault that was disconnected or not synced for some time.
This can be because you go weeks without touching Obsidian on a particular random device and then when it is getting caught up, Sync can get confused and lose random edits and changes. Plus, that syncing time to get it caught up can take a while.
This usually happens when you make edits on that device since the last time it synced. Like if sync got broken or you were off a network, or snoozed the device before it had finished syncing.