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).

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:

shell
docker compose ps
docker compose logs --tail 100 app
docker compose logs --tail 100 postgres

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:

shell — which data volumes actually exist?
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:

Edits are not syncing / the status pill says "Can't reach server"

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).