Troubleshooting
The handful of problems pre-1.0 Lecture actually has, and what to do about each. When this page runs out, write to hello@nilox.network — describe what you saw and what you ran, and you will get an answer.
The first load spins and shows nothing for a while
Expected, and the most common "is it broken?" moment. Lecture is a WebAssembly app: the first visit downloads the entire application, which is much more than a normal web page. The status page stays visible meanwhile; the app appears when it is ready and opens near-instantly on every visit after that (the browser caches it as an installable PWA).
- Give a fresh instance a few minutes on a slow link before worrying.
- If it never finishes: reload once. Then check the browser console and
docker compose logs app— a reverse proxy that buffers large responses or blocks WebSockets is the usual suspect. - Hard-reload (Ctrl/Cmd+Shift+R) after a server update if the app seems stuck on an old version.
The app container exits or restarts in a loop
Nine times out of ten this is the database. Look at the app's own log first:
docker compose ps
docker compose logs --tail 100 app
docker compose logs --tail 100 postgres
- Startup before the database was ready. The example compose file waits for the database health check; if you removed
depends_on, put it back — or simply rundocker compose up -dagain oncepostgresis healthy. - Connection refused / authentication failed. The password in
ConnectionStrings__Lectureand in the database service must match — and remember the database password is fixed when its volume is first created (see Configuration).
Compose complains that the data volume does not exist
If you followed the advice to keep the database data in a volume that Compose does not own (declared external: true), Compose refuses to start when that volume is missing — it errors instead of silently creating a fresh, empty database next to your real one.
This failure is a guard, and a good friend: it means the volume name Compose looks for and the volume that exists have drifted apart. Find the truth and fix the name — do not just create a new empty volume with the expected name:
docker volume ls | grep postgres
Data "disappeared" after a restart, move or update
Almost always the stack is running against a different (empty) volume, not that data is gone:
- Named volumes follow the Compose project name (the folder name, unless
name:is set). Copied the folder elsewhere or renamed it? You got a new, emptyproject_postgres-data. - Check with
docker volume lsfor the old volume, stop the stack, pointcompose.yamlback at it, and start again. Your data was in the volume the whole time. - This is also why
docker compose down -vanddocker volume pruneare banned words on a Lecture host.
Edits are not syncing / the status pill says "Can't reach server"
- Which side is offline? The pill describes your device's connection. If it is just you, check your network; if everyone sees it, check the server containers.
- Sync uses WebSockets. Everything else working (login, pages) but live updates not arriving is the classic sign of a proxy without WebSocket forwarding enabled. Turn it on; nothing in Lecture needs reconfiguring after.
- Offline is a normal state, not an error. Keep typing; the pill flips to Syncing and then Synced on its own. Offline edits merge automatically — two people, same paragraph, no lost letters.
- If one device loops between Syncing and Offline: reload; if it persists, check the browser console for a blocked connection (wrong URL behind a proxy, mixed HTTP/HTTPS, an aggressive content blocker).
Login problems after a restore or rollback
Sign-in state is tied to the database. After restoring a backup or rolling the database back, previously issued login cookies may no longer validate: sign out and sign in again before debugging further. If login fails on every browser, compare the running app version with the database's version (one version at a time applies to databases too).