Troubleshooting

The common issues, and how to fix them.

`502 Bad Gateway` after loading the page

Almost always BACKEND_ORIGIN pointing at the wrong place. It’s resolved over the internal Docker network, so it must use the backend’s service name (backend), not your host or LAN IP.

connect() failed (111: Connection refused)

Pointing it at something like 192.168.1.10:3000 fails because the backend isn’t published to the host — only exposed on the Docker network. Fix: leave it as backend:3000, or change only the port if you set a custom backend PORT (e.g. backend:3008). See Configuration.

Make sure JWT_SECRET is set to a strong value (32+ characters) in .env and that you restarted after changing it:

docker compose up -d

Changing JWT_SECRET invalidates existing sessions — log in again.

Port already in use

If host port 80 is taken (another web server, or a reverse proxy), move Lyftr to a free port with PORT=8080 in .env, then restart. If you’re running a reverse proxy, see HTTPS & Reverse Proxy.

The mobile app or another device can’t connect

The app needs a reachable server URL. Use a real hostname over HTTPS (reverse proxy) — localhost won’t work from a phone, and plain HTTP exposes your login token to everyone on the network.
Add that origin to CORS_ORIGIN (comma-separated), or use * to allow any (the API is Bearer-token based, so there are no cookies to protect).

A native app sends no Origin header, so the backend never applies CORS to it. If the phone app says it can’t reach the server but the same URL works in the phone’s browser, the device is blocking the connection, not the server. The two common causes:

Plain http:// — blocked by Android’s defaults. The app opts back in, at the cost of sending your login token unencrypted; prefer HTTPS. See HTTPS & Reverse Proxy.
A private or self-signed CA — apps ignore the user-installed CA store unless they opt in. The app does, but the CA still has to be installed on the device. See HTTPS & Reverse Proxy.

Both need a current build, which also names the specific cause in the error message instead of guessing. If you get a generic message mentioning CORS, update the app first.

Barcode scanner won’t open in the web app

It says Camera needs HTTPS because your instance is served over plain http://. No Lyftr setting changes this — put it behind HTTPS and the scanner works. Your own private CA is enough.

Unaffected: http://localhost on the server itself, and the Android app, which uses the phone’s camera rather than the browser’s.

No exercises show up

They seed in the background on first startup and appear within a few seconds. If the list is empty, check the logs and use Settings → Exercise Library → Re-sync. See Exercise Library.

docker compose logs backend | grep -i seed

Still stuck?

Open an issue on GitHub or ask in the Discord — include your docker compose logs output.