Troubleshooting#

Problems with something you are hosting or building yourself.

Proxy#

It returns a website instead of a stream#

Your reverse proxy is serving its own page rather than passing through to the container. Check the container directly first:

curl http://localhost:3000/health

If that answers, the problem is between your reverse proxy and the container, not in the proxy.

It works over http but not from the site#

A browser on an https:// page refuses to call an http:// proxy. Put it behind TLS. There is no way around this from the site's side.

Sources fail through your proxy but work through the default one#

Your server's IP is being refused by that source. Datacentre ranges are widely blocked; a residential IP, or the extension, gets past it where a VPS won't.

502s that look like CORS errors#

If something in front of the proxy (Cloudflare especially) replaces an origin error with its own page, that page has no CORS headers, so the browser reports a CORS failure rather than the real status. Check the proxy's own logs for what it actually returned.

Backend#

/health says the database is down#

DATABASE_URL is wrong, or Postgres isn't reachable from inside the container — localhost in a container is the container, not the host. Use the compose service name.

Everyone's account data suddenly fails to decrypt#

CRYPTO_SECRET changed. It is not recoverable and nothing re-encrypts on the fly; restore the old value.

Registration rejects everyone#

With CAPTCHA=true, both CAPTCHA_CLIENT_KEY and CAPTCHA_SECRET have to be set. Turnstile keys are per-domain, so a key minted for another host fails every check.

Keep Postgres off the internet#

Docker writes its own iptables rules and goes straight through ufw, so a published 5432 is your database on the public internet regardless of what your firewall says. Use expose rather than ports and let the backend reach it by service name.

Extension#

The site doesn't see it#

Reload the tab — the site only looks for the extension on load. Then check your browser's extensions page: some browsers install extensions in a restricted state, and nothing works until you grant the optional host permission.

It builds but won't load#

Load the build output directory, not the repo — build/chrome-ps-prod for Chromium, and the .xpi for Firefox. Firefox additionally refuses unsigned extensions on release builds; use Developer Edition or Nightly, or sign it.

Desktop app#

It won't start on macOS#

The app isn't notarised. System Settings → Privacy & Security → Open Anyway, once.

The build fails on pnpm install#

The workspace file uses pnpm 10's onlyBuiltDependencies. On pnpm 9 it fails with packages field missing or empty — upgrade pnpm.

Video stutters or the window draws wrong#

Turn off hardware acceleration in Settings → Application and restart. Some older or hybrid GPUs advertise a decoder they can't actually drive.