When Obsidian Self-hosted LiveSync stalls at 761/23585 on a new device's first sync (fast-fetch heartbeat bug #953)

Environment: Obsidian 1.12.7 (Kubuntu 26.04) · Self-hosted LiveSync (CouchDB backend) · ~300 notes (23,000+ CouchDB documents)

TL;DR

If a new device's first fetch stalls at the same spot every time on a vault with thousands to tens of thousands of documents (notes + chunks), it's LiveSync Fast fetch's missing heartbeat (~60s cut). Don't use the Setup URI's automatic fetch — bring it in with the "Reset and Resume Synchronisation" wizard instead, which uses a batch method that doesn't hit the streaming timeout.

The symptom

An Obsidian vault runs on Self-hosted LiveSync (CouchDB). The four existing devices (Windows, phone, Raspberry Pi, mini PC) were already synced and fine, but attaching a freshly set-up Kubuntu desktop, the initial cold fetch stalled at the same place every time.

Attaching via Setup URI runs "Fast fetch" automatically, and the progress stalled around 761–781 / 23585 every time, per the console log the user sent.

That "23,585 documents" isn't a note count. There are only ~300 actual notes — LiveSync splits each note's content into multiple chunks, and with orphan chunks and huge plugin chunks piled on top (see "Side cleanup" below), the CouchDB document count ballooned to this. And the more documents to fetch, the more reliably it hits the 60-second cut below.

Starting initial synchronisation. ... Total documents to fetch: 23585
Fast fetch progress: 25 / 23585
Fast fetch progress: 50 / 23585
...
All documents fetched. Stopping the stream…
Error during vault initialisation process

It needs to receive 23,585 documents, but in the 700s it suddenly claims "All documents fetched," closes the stream, tries to initialize the vault with ~700 docs of incomplete data, and throws Error during vault initialisation process. Then reset → retry → stall at the same place, looping forever, never completing.

The misdiagnosis (where all the time went)

Because the stall point was always similar, I first suspected "is a specific document around #761 corrupted?" The following were all not the cause — noted for anyone chasing the same thing.

• Plugin version: swapping 0.25.83 ↔ 0.25.73 failed identically. Unrelated.
• E2EE algorithm: phone and Linux both on V2, matching. Unrelated.
• Transport (tailscale): the streaming _changes response — 23,560 lines, 46MB buffer — was delivered intact, byte-identical to a direct localhost fetch. Not truncated in transit.
• Local cache cruft: a brand-new empty vault failed the same way. Not a client cache issue.
• Corrupt/huge/unencrypted docs: a full CouchDB scan found 0 dangling references, 0 unencrypted leaf chunks, 0 corrupt deletion entries. Not a specific-document problem.

So every "specific document" or "clean the data" angle was a dead end.

Root cause: not a specific document but a time-based cut (no heartbeat)

The stall landing at 761–781 every time was actually two things stacked. At first a huge plugin chunk (see "Side cleanup" below) blocked the fetch up front around 761; once that was cleared, the stall moved to 781 — and what remained was a pure time-based cut, breaking not at a specific document but at "the number of documents received in about 60 seconds." That's the key.

LiveSync's Fast fetch opens the CouchDB _changes streaming connection with no heartbeat. So about 60 seconds after the connection opens, CouchDB treats it as idle and drops it. The client mistakes that normal close for "received all documents," closes the stream, and fails trying to initialize the vault from the ~700 docs of incomplete data. The more documents to fetch (the less it can finish within 60s), the more reliably it hits — here, even with only ~300 notes, chunking ballooned the count past 20,000, so it couldn't finish in 60s. With few enough documents to complete inside 60s, the bug never shows.

It's already reported upstream — GitHub vrtmrz/obsidian-livesync #953.

The fix: the detailed flow (don't use Fast fetch)

For a new device's first sync, don't use the fast fetch the Setup URI runs automatically — bring it in with the manual reset wizard. It uses a batch method that doesn't hit the streaming timeout.

In the plugin settings, open the "Reset and Resume Synchronisation" wizard, and I asked the user to choose:

• Vault state: "This Vault is empty, or contains only new files that are not on the server." (attaching fresh as an empty vault)
• Backup confirmation: "I have created a backup of my Vault."
• Under Advanced, leave "Prevent fetching configuration from server" unchecked (you need to pull the server's E2EE settings).

Fetched this way, it ran all 23,000+ documents to completion. Tip: make a fresh empty folder with your real vault name and attach it via this procedure for a clean start.

Side cleanup: keep Customization Sync off

Separately during diagnosis, I found the DB bloated to 26× the actual vault (2.8MB). The cause was LiveSync's Customization Sync storing plugin main.js files as single huge monolithic chunks — and one of those huge chunks was also jamming the fetch up front. I asked the user to clean those documents and huge chunks out of CouchDB and compact.

Prevention: keep LiveSync's Customization Sync off on every device. Left on, it re-accumulates plugin binaries as huge chunks that bloat the DB and block fetches. Syncing themes, snippets, and appearance is fine; just install plugins per-device.

Takeaways / checklist

• When the CouchDB document count (notes + chunks) runs into the thousands or tens of thousands, always bring a new device in via the detailed flow (Reset and Resume). Fast fetch has no heartbeat and fails at the ~60s cut (until upstream #953 is fixed). Even with few notes, chunk/orphan-chunk bloat can push the document count high enough to trigger it.
• When the stall point is "a similar number every time," suspect a time-based cut (timeout), not a specific document. It may be "how much arrived in N seconds," not "the Nth document."
• Manage DB bloat (orphan chunks, plugin binaries) separately from this bug — turn off Customization Sync so it never accumulates in the first place.