Troubleshooting
Voice depends on the site, the site on the proxy, and each layer can look fine while the one above it is broken. Climb the ladder in order and stop at the first rung that fails. Never test only from inside your own network.
The container will not start
If docker compose ps shows the app restarting, read the log:
docker compose logs app
A missing or placeholder required setting is reported all at once, under Mnema Talk cannot start - fix these settings in .env:. Fix every listed line and run docker compose up -d. Before a start, setup --check prints the same list:
docker run --rm -v "$PWD:/out" ghcr.io/mnema-xyz/mnema-talk setup --check
The ladder
- The site. Open
https://chat.example.comon a phone with Wi-Fi off. No padlock and sign-in page? The DNS record, the 443 forward or the certificate. From a computer:curl -I https://chat.example.com. - Live updates. Sign in. “Connection lost – reconnecting…” means the proxy does not pass the WebSocket: in the developer tools (F12 > Network, filter "WS")
/api/wsmust be status 101. Fix it. - Admin > Status. Wait about twenty seconds after a start. Every amber or red item says what to change. Green does not prove that your router forwards UDP; the server cannot test that from inside.
- Test my connection. In Admin > Status, opened from a phone on mobile data: direct UDP works, only the relay works (calls work, but fix the UDP forward), or nothing works (check the router, the firewall and CGNAT).
- A real call between two networks. A computer on Wi-Fi and a phone on mobile data join a Talk. Audio both ways within about two seconds.
Symptoms, causes, fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The site does not load | DNS, 443 not forwarded, certificate | Fix the A record, forward 443 and 80, check the certificate |
| Site loads, chat dead, “Connection lost” | The proxy does not pass WebSockets | Enable WebSockets |
| 403 on sign-in or on every request | PUBLIC_URL does not match the address in the browser | Set PUBLIC_URL to exactly that address, docker compose up -d |
| Everyone shares one rate limit, or gets locked out together | The app sees the proxy's address instead of the visitors' | Put the address Status > Reverse proxy names into TRUSTED_PROXY_CIDRS |
| Works on the LAN, not from outside | UDP 50000–50050 not forwarded, host firewall, wrong announced address | Forward the whole range, open the host firewall, check webrtc announce |
| Works from outside, not on the LAN | The router has no NAT loopback | Set WEBRTC_LAN_IP to the server's LAN address (details) |
| Nobody outside ever connects, ports are forwarded | CGNAT or DS-Lite: no public IPv4 | Check your line; move to a VPS |
| Connects, then drops after seconds | Wrong announced address, or part of the range forwarded | Check webrtc announce; forward the whole range |
| One person cannot join, the others can | Their network blocks UDP | Forward 3479 on UDP and TCP; try another network |
| A port stays closed though forwarded | Host firewall or cloud security group | Open it in both places |
The voice logs
docker compose logs --since 10m app | grep -E 'webrtc announce|setup check|sfu ice|webrtc client diag'
webrtc announceat startup shows the public IP the server tells browsers. Only a172.xor10.xaddress there means the detection failed: setWEBRTC_NAT_1TO1_IP.sfu ice connectedappears when a member's media path is up;remote_typerelaymeans that member came in through the TURN relay.sfu ice failedand awebrtc client diagline with"ice":"failed"mean packets from that member do not arrive.
In the browser, chrome://webrtc-internals (Firefox: about:webrtc), opened before you join, shows the candidate pair that carries the media: relay means the relay carries it, srflx or host means direct UDP works.
Probe the relay from outside
scripts/turn-probe.py (standard library only) checks from another network that the relay answers on UDP and TCP. Copy it from the repository and run it outside your network:
TURN_PROBE_HOST=chat.example.com python3 turn-probe.py
It ends with RESULT udp: PASS and RESULT tcp: PASS, or FAIL. FAIL on one protocol only means you forwarded just the other one.
The Owner cannot sign in
Repeated wrong passwords lock a client address for a while. Clear it from the host, even when nobody can sign in:
docker exec mnema-talk /usr/local/bin/mnema-talk unlock USERNAME
unlock --all clears everybody. The Owner can also clear a member's lock in Admin > Members. A lost authenticator: mnema-talk reset-2fa OWNER_NAME, see Security hardening.
Still stuck?
Read the voice troubleshooting guide and the repository FAQ, then ask in Discussions with the output of mnema-talk doctor. Bugs go into issues.