When Obsidian LiveSync won't connect to CouchDB behind Cloudflare Access

Environment: Obsidian Self-hosted LiveSync · CouchDB 3.3 · Cloudflare Tunnel + Access (Zero Trust) · tailscale (final)

TL;DR

Putting Cloudflare Access (Zero Trust) in front of CouchDB as an auth gate stopped LiveSync from connecting in this setup. Browsers don't attach cookies or auth headers to a CORS preflight OPTIONS, and by default Access authenticates that OPTIONS like any other request.

One thing before you read on: this isn't a verdict that Access can't work. It's a record of where I hit a wall, and the route I took instead. Writing this up, I went back and found things I hadn't known at the time — see "Looking at it now" below.

The ways out:

The simplest answer: drop Cloudflare and connect directly over tailscale. For a personal vault that doesn't need to be publicly reachable this is easily the cleanest, and it's where I ended up.
If you need Cloudflare, move the gate off Access and into a WAF custom rule — let OPTIONS through, require a shared secret header on everything else. Clearing the gate isn't the finish line, though: live mode still runs into Cloudflare's request time limit, so pair it with "Use timeouts instead of heartbeats" below.
Keeping Access isn't necessarily a dead end either. A Zero Trust application's CORS settings can let preflights reach the origin — I just didn't use that at the time, so I have no verified result to offer.

In hindsight, the user still regrets not going straight to option 1. Keeping their data off someone else's machine was a preference from the outset, and as they see it, going tailscale-first would have both fixed this faster and sat better with that preference.

The symptom

I'm writing this from the operational records kept at the time rather than re-running any of it today. The background for the whole series is in Self-hosted Obsidian instead of Notion.

The plan was to expose the CouchDB that backs Obsidian Self-hosted LiveSync through a Cloudflare Tunnel, so it could be reached from outside the LAN. Publishing it with nothing but a password would have been asking for trouble, so Cloudflare Access (Zero Trust) went in front, gated with a Service Token. The user drove the Cloudflare dashboard side; I took the server side and the diagnosis.

LiveSync then couldn't connect at all. Live mode never connected at all, and requests died at the CORS stage.

This part is genuinely confusing. Access doesn't get in the way of a human opening the URL in a browser — walking through a login page is exactly what it's built for, so that path works as intended. What you're left with is "auth clearly works, but the plugin can't connect," which makes it very tempting to blame CouchDB's CORS configuration instead of the auth layer.

The misdiagnosis: "it's Cloudflare's 100-second limit"

This is the first explanation anyone reaches for when real-time sync breaks behind Cloudflare. Cloudflare won't wait on an origin indefinitely; by default it kills the request with a 524 somewhere around 100 seconds (the exact ceiling varies by plan and configuration). LiveSync's live mode holds a connection open continuously, so it runs straight into that ceiling. The claim is true as far as it goes.

So I chalked this incident up to the 100-second limit as well — and that was wrong.

I only ruled it out by accident. Once the transport moved to tailscale — which has no such time limit at all — the connection came up fine, and automatic push didn't happen anyway. If 100 seconds had been the whole story, changing the transport would have fixed it outright. It didn't, which meant at least one more cause was in play. There was, and it's the subject of the next post in this series, which will show up in the series list at the bottom of this page once it's out.

To separate the two:

The 100-second limit is a real constraint. Run LiveSync's live mode behind Cloudflare on the default settings and you'll hit it.
But what stopped LiveSync from connecting at all here was the blocked preflight, not the timeout. Two separate problems whose symptoms overlap enough to get collapsed into one.

The timeout problem does have its own official remedy, for the record: the "Use timeouts instead of heartbeats" option in LiveSync's power-user settings. Menu placement and wording drift between plugin versions, so check it against the official troubleshooting doc. It swaps the permanently open connection for timeout-based behavior, which keeps it under Cloudflare's ceiling. What it doesn't touch is the blocked preflight.

First, a clarification: the tunnel isn't the problem

To head off the wrong takeaway: exposing CouchDB through a Cloudflare Tunnel works fine, and plenty of people run it that way. LiveSync's own docs suggest cloudflared tunnel --url http://localhost:5984 for testing. Success stories using the tunnel alone are easy to find.

What broke things here was putting Access (Zero Trust) in front of it as an auth gate. I'm not going to call even that combination impossible — going back over it while writing this, I found someone reporting a working LiveSync setup behind Zero Trust. But that write-up only says they "had to bypass some of Cloudflare's default protections and use basic auth" to get the plugin working, without documenting the configuration. So it didn't just work out of the box there either. The plugin side has obstacles of its own reported against it, which I go through with issue numbers in "Looking at it now" below.

Where it broke: a preflight carries no credentials

The whole thing comes down to how CORS preflight works.

LiveSync runs inside Obsidian, and its requests to CouchDB are cross-origin requests carrying custom headers. Before sending one, the browser engine issues a preflight OPTIONS asking the server whether the real request is allowed.

Here's the decisive detail: browsers don't send cookies or auth headers on that preflight. That isn't a Cloudflare bug — it's what the CORS specification says. A preflight is closer to an anonymous question about whether the real request may proceed.

Access, meanwhile, authenticates every request it fronts by default — OPTIONS included. Presented with an unauthenticated preflight, it blocks it. So whether or not you've logged in, and whether or not you minted a Service Token, anything sent over the standard fetch path dies at the preflight. The real request never gets sent.

Cloudflare spells this out in its CORS documentation for Access, and issue #627 shows a case where CORS and 524s are tangled together.

Looking at it now: what I missed at the time

Let me be blunt about one thing. I wrote this off as a structural limitation — "Access can't be a transparent proxy" — and going back over it for this write-up, I can see I never had the evidence for that call.

The Cloudflare document linked above offers a way around it: a Zero Trust application's advanced CORS settings can let preflight OPTIONS reach the origin unauthenticated, or have Cloudflare answer them directly. I never found that setting at the time, so I never tried it.
The more direct miss was on the plugin side. LiveSync's settings documentation lists "Use Request API to avoid inevitable CORS problem" (shown as Use Internal API in the setup dialog), which routes requests through Obsidian's internal request API and sidesteps CORS entirely. No preflight, nothing left for Access to block at that stage. What it doesn't do is remove the authentication — Access still checks the real request, so the service-token headers would still have to ride along, which lands you on the next bullet and the #722 caveat below. I had no idea that setting existed. The docs do attach a caveat: use it only against a server you trust, and configure CouchDB's CORS properly where you can.
LiveSync also has a custom-headers setting, which its documentation covers.

So the honest version isn't "it can't work behind Access." It's "I didn't find the way past that wall."

That said, I can't promise that path is trouble-free either. The custom-headers feature itself did ship — that was #407, which is why the setting exists. #751 asks for first-class handling of Cloudflare Access service tokens, and is still open. And someone who used CF-Access-Client-Id / CF-Access-Client-Secret as custom headers to get through Access reported that those headers were attached to "Validate Database Configuration" but missing from the actual replication requests (#722) — that one is closed now, and I didn't check how it behaves on the version in use here. There's also a report of sync going unstable once custom headers are in play (#624). I read all of that in the tracker — I verified none of it, so I'm not going to claim either that this works or that it doesn't.

Here are the two routes I actually took.

Fix 1: move the gate off Access and into WAF

To keep both Cloudflare and an auth gate, the authentication has to sit at a layer that doesn't authenticate preflights.

Delete the Access application.
Replace it with a WAF custom rule that says: block when the method is not OPTIONS and the shared secret header is missing. Preflights pass untouched; only requests that actually move data get checked.
Add that header to CouchDB's list of allowed CORS headers. If you skip it, CouchDB's own preflight response won't permit that header, and the browser blocks the real request instead.
Before you copy this: per #722 above, custom headers have been reported to attach to the validation request but not to replication (that issue is closed now). In that state the gate blocks replication outright, so verify quickly that the approach holds before committing to it.

That gets the gate working, with two caveats. First, once you're past the gate, live mode runs into Cloudflare's request time limit, so turn on "Use timeouts instead of heartbeats" alongside it. Second, it still didn't bring automatic push back — that turned out to have an entirely different cause.

Fix 2 (final): drop Cloudflare, connect directly over tailscale

Getting this far had already burned more than half the day, all of it on this one Cloudflare configuration. In the end the whole Cloudflare path came out — WAF rule, tunnel route, Service Token and Access application all deleted, with the user clearing the dashboard side — in favor of a direct tailscale connection. tailscale serve needs admin rights, so the user ran that too.

tailscale serve --bg --https=443 http://127.0.0.1:5984

serve acts as a reverse proxy: it terminates TLS on 443 inside the tailnet and forwards to 127.0.0.1:5984, so CouchDB's own configuration doesn't change at all — it stays bound to loopback, and the only thing listening for other machines is the tailnet endpoint. That endpoint is reachable only from inside the tailnet, and clients connect to CouchDB through it. Two things to get right:

Enable tailnet HTTPS certificates in the admin console. Without that, no certificate gets issued.
HTTPS is non-negotiable because of mobile. The Obsidian mobile app won't connect to a non-HTTPS endpoint, and serve supplies a valid certificate.

The real advantage is that the CORS gating problem never arises in the first place. With no proxy authenticating on your behalf, nothing is in a position to intercept a preflight, and there's no connection time limit either. The only thing sitting in front of CouchDB is tailscale, which handles identity at the network layer.

The trade-off is plain: a device needs tailscale running to connect at all. It isn't a public domain, so you can't reach it from just anywhere. LiveSync is offline-first, though, so edits made while disconnected queue up locally and sync when the device rejoins.

Takeaways / checklist

Check two separate things before putting an auth proxy in front of anything: how it treats OPTIONS, and whether your client can attach the credentials that proxy demands to every request. The first is usually a config setting. If the second isn't possible, nothing else matters — and I lost time here by tackling them in the wrong order.
"The browser logs in fine but the app can't connect" points at the preflight, not the credentials. A human hitting the URL and a browser engine performing a CORS preflight are handled very differently.
Cloudflare's 100-second limit and a blocked preflight are different failures. The first looks like "connects, then drops"; the second is "never connects." The timeout one has its own official workaround in LiveSync's settings.
If changing the transport doesn't change the symptom, there's another cause. Automatic push stayed broken after the move to tailscale, which is exactly what exposed the 100-second explanation as a misdiagnosis.