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

  1. The site. Open https://chat.example.com on 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.
  2. Live updates. Sign in. “Connection lost – reconnecting…” means the proxy does not pass the WebSocket: in the developer tools (F12 > Network, filter "WS") /api/ws must be status 101. Fix it.
  3. 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.
  4. 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).
  5. 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

SymptomLikely causeFix
The site does not loadDNS, 443 not forwarded, certificateFix the A record, forward 443 and 80, check the certificate
Site loads, chat dead, “Connection lost”The proxy does not pass WebSocketsEnable WebSockets
403 on sign-in or on every requestPUBLIC_URL does not match the address in the browserSet PUBLIC_URL to exactly that address, docker compose up -d
Everyone shares one rate limit, or gets locked out togetherThe 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 outsideUDP 50000–50050 not forwarded, host firewall, wrong announced addressForward the whole range, open the host firewall, check webrtc announce
Works from outside, not on the LANThe router has no NAT loopbackSet WEBRTC_LAN_IP to the server's LAN address (details)
Nobody outside ever connects, ports are forwardedCGNAT or DS-Lite: no public IPv4Check your line; move to a VPS
Connects, then drops after secondsWrong announced address, or part of the range forwardedCheck webrtc announce; forward the whole range
One person cannot join, the others canTheir network blocks UDPForward 3479 on UDP and TCP; try another network
A port stays closed though forwardedHost firewall or cloud security groupOpen 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 announce at startup shows the public IP the server tells browsers. Only a 172.x or 10.x address there means the detection failed: set WEBRTC_NAT_1TO1_IP.
  • sfu ice connected appears when a member's media path is up; remote_type relay means that member came in through the TURN relay.
  • sfu ice failed and a webrtc client diag line 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.

Something wrong on this page? Tell us.