Troubleshooting¶

The scanner camera doesn't work¶

Browsers allow the camera only on https:// or localhost. Check that the app runs over HTTPS and allow the camera in the browser's site settings.

CSRF error (403) after submitting a form¶

The domain is missing from CSRF_TRUSTED_ORIGINS in .env. It must contain the full origin including the scheme, e.g. https://odbavto.example.com. Behind a proxy, BEHIND_PROXY=True is required.

Bad Request (400)¶

The domain or IP you use to open the app is missing from ALLOWED_HOSTS.

502 Bad Gateway behind Caddy¶

The web container is not running or is still starting (migrations): docker compose logs -f web.
Caddy is not on the web network, or the container name in the Caddyfile doesn't match (<COMPOSE_PROJECT_NAME>-web:8000).

The scanner keeps flipping between connected and disconnected¶

The WebSocket drops every ~5 s. REDIS_SOCKET_TIMEOUT must be more than 5 (default 30). Restart the app after changing it.

WebUSB: the printer is not offered when pairing (Windows)¶

Windows holds the printer with its own driver. Install WinUSB with Zadig, see Printers. WebUSB works only in Chrome and Edge.

The network printer doesn't print¶

Check ping <IP> from the server and port 9100. For Brother QL see Brother troubleshooting. If the server runs in the cloud, it cannot reach a printer on a local network. Use the agent.

The agent prints twice¶

Two agent instances with the same token are running for the same printer. Keep only one.

Agent: `NoBackendError` (macOS / Linux)¶

The libusb library is missing: brew install libusb (macOS) or sudo apt install libusb-1.0-0 (Linux).

Agent: `Access denied` (Linux)¶

USB access without root requires a udev rule. Alternatively, install the printer in CUPS and the agent prints via lpr.

Direct: the printer doesn't print (Windows)¶

The printer name in the app must exactly match the name in Windows (Printers & scanners). python agent.py --list-printers lists the names.

A hostess sees "check-in is not open yet"¶

The event has no active check-in queue. Create or activate a queue in Settings → Access.

Translations don't show (local installation)¶

python manage.py compilemessages

Then restart the server and clear the browser cache.