Why an auto-generated file that changes every 10 minutes causes sync conflicts in Obsidian — and the dotfile that fixes it

Environment: Obsidian Self-hosted LiveSync + CouchDB 3.3 · livesync-bridge (Deno) · 5 syncing devices today; 4 at the time of this incident

TL;DR

Don't give a self-updating file an ordinary name inside the vault. Every device ends up holding its own version of it, and Obsidian treats that as a sync conflict.

• Give it a dot prefix and it goes quiet: the bridge still syncs dotfiles, while Obsidian clients ignore hidden files by default.
• That only holds while the client's "sync hidden files" option is off — which is the default. Turn it on and the conflicts come straight back.
• Avoiding a leading _ is still a good habit. What decides it isn't the filename but the first character of the path from the vault root. If that's _, it breaks — by syncing under a different name rather than failing to sync, and created from the app it split into two documents (we checked this). _folder/note.md is caught for the same reason; 0_Dashboard/_note.md isn't.

Where the file came from

I'm writing the incident itself from the operational records kept at the time rather than re-running it today — though the naming rule further down is something we did check this time. The background for the whole series is in Self-hosted Obsidian instead of Notion.

One direction of sync had died without raising a single error, and catching a repeat of that automatically meant adding a heartbeat watchdog: the authoritative machine writes the current time into a vault file every 10 minutes, and the watching machine checks how stale that timestamp is.

Which means a file inside the vault now rewrites itself every 10 minutes. That's the whole setup for this one.

Three names

First try: _pull_heartbeat.md — which synced perfectly well.

The leading underscore was meant as nothing more than "this is a system file, keep it out of the way." And right after I set it up it worked: the timestamp written on the authoritative machine reached the watcher, and the user could see the file sitting there in Obsidian.

Then I renamed it myself. The vault rules I keep say a file starting with _ breaks, because CouchDB reserves document IDs that begin with an underscore — and I noticed, after the fact, that I had just broken that rule. It was working, but I judged it might trip up the clients, so I renamed it as a precaution.

Checking the server while writing this post, I found the worry had nothing behind it. CouchDB still holds a 3_resources/system/_pull_heartbeat.md document, sitting at revision 3. Document IDs in this vault are the lowercased path (0_dashboard/dashboard.md and so on), so this file's ID starts with 3_resources/…. It doesn't begin with an underscore, so the reserved-ID rule never applied.

The rule itself is worth keeping. Writing this post, we made a _ file at the top level from each side and I read both results back. I made a _ file on the server's filesystem; the user made one in the phone app; and I read the resulting document IDs back out of CouchDB.

It does break at the top level — just not by failing to sync. The name splits.

The _synctest.md I created on the server's filesystem went up under the ID synctest.md: the bridge dropped the underscore. Creating it in the app goes wrong in the opposite direction. The app uploads it as /_name, a shape that steps around the reservation; the bridge then writes that document to disk with the underscore removed and pushes the file it just created back up as a second document. One file, two documents, two names.

So what the rule was missing was the path: what counts is the first character of the path from the vault root, not the filename. _pull_heartbeat.md had a path starting with 3_Resources/…, so it was never in scope — while a top-level folder named with a leading underscore loses that underscore too, taking everything inside it along — which I also made and checked this time. And without checking that condition I wrote the episode up as a trap I'd walked into — an account that made it into the CouchDB post in this series too, and got corrected there at the same time as here.

Second try: pull_heartbeat.md — where I misread the cause.

The real problem had nothing to do with the name. The desktop and the phone both reported sync conflicts, and the user had to pick which version to keep — right when a device that had been offline for a while came back. The same thing had happened under the first, underscore-prefixed name too: what produced the conflicts wasn't the name, it was that the file was visible in the vault.

The mechanism is simple enough. The file gets new contents every 10 minutes, several devices sync it, and some of them sit switched off for long stretches. The moment such a device reconnects, the copy it was holding diverges from the one on the server — and with a self-updating file, that situation keeps re-creating itself. A fresh conflict candidate appears every 10 minutes without anyone editing anything.

It's also plainly visible in the vault, so from the user's side there's a file they never created sitting in the file list, generating conflicts on its own.

Third try: .pull_heartbeat.md — quiet.

A dot prefix works because two things line up:

• The bridge syncs dotfiles. I confirmed that by pushing one through. So the monitoring keeps working exactly as before.
• Obsidian clients ignore hidden files by default. The file stops appearing in the file list on desktop and mobile, and since the client never tracks versions of it, there's nothing to conflict.

The file ends up in the one place that still syncs while staying invisible to the app.

The precondition

This fix is conditional. The client's "sync hidden files" setting has to stay off. It's off by default, so most setups get this for free — but switch it on and the app starts managing dotfiles too, at which point the conflicts come straight back.

And "hidden" doesn't mean gone. The file is still there and still syncing. The app simply doesn't treat it as one of its documents.

A note on the cleanup

Renaming meant clearing out the old file and the conflict copies that had piled up. The ones left on the desktop were deleted by the user from within Obsidian.

At the time I believed deleting from the client was the safer route, and that's what I advised. That call was later reversed — deleting from the client turned out to be the direction where deletions went missing, and the server filesystem was the reliable one. That gets its own post later in this series; here I'm only recording what was actually done.

Takeaways / checklist

• A continuously changing file inside a synced folder is a conflict factory. Nobody has to edit it: versions diverge across devices on their own, and every update cycle sets the situation up again.
• If an auto-generated file has to live in the vault, put it where the app doesn't look. In Obsidian that's a dot-prefixed file — a conditional fix that depends on a client setting, so write the condition down next to it.
• Don't manufacture an incident out of a rule you wrote yourself. I decided I'd broken the rule, renamed the file, wrote that up as a trap I'd fallen into, and shipped it in a post. The server says the file had been syncing the whole time. Following a rule and claiming it caught you are two different things.
• Say "generated, do not edit" inside the file itself. It's the cheapest way to stop whoever — or whatever session — opens it later from editing it.