Troubleshooting: the site, live updates and voice

From mnema-talk v3.3.13, rendered on this site.

Work from the bottom up. Voice depends on the site, the site depends on the proxy, and each layer can look fine while the one above it is broken. Never test only from inside your own network: nearly every voice problem is invisible from there. Terms are in the glossary.

The container will not start

If docker compose ps shows the app restarting, read docker compose logs app. A missing or placeholder required setting is reported all at once:

Mnema Talk cannot start - fix these settings in .env:
  - ...

Fix every listed line in .env (the six required settings are in Settings at a glance) and run docker compose up -d. The app exits with status 78 in this case. Before the first start, docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/out" ghcr.io/mnema-xyz/mnema-talk setup --check prints the same list for the .env in the current folder. Other startup messages are explained under The app does not start.

The ladder

Check each rung in order and stop at the first one that fails.

Rung 1: the site

Open https://chat.example.com on a phone with Wi-Fi off. Expected: a padlock and the sign-in page. If not: the DNS A record does not point to your public IPv4 address, TCP 443 (and 80 for certificates) is not forwarded or not open in the firewall, or the certificate is wrong. See TLS certificates. From a computer: curl -I https://chat.example.com.

Rung 2: live updates (WebSocket)

Sign in. The page must not show "Connection lost – reconnecting…" and messages must arrive without a reload. If it does show it, the proxy does not pass the WebSocket. In the browser's developer tools (F12 > Network, filter "WS") the request /api/ws must be status 101; 400, 426 or 502 mean missing Upgrade and Connection headers. Fix: WebSockets. Admin > Status has a WebSocket item for this.

Rung 3: Admin > Status

Open Admin console > Status as the Owner and wait about twenty seconds after a start. Every amber or red item says what to change. What the items mean:

ItemPlain meaningRed or amber means
Public addressPUBLIC_URL: the address members typeAmber: it is localhost (fine for a trial on one computer), plain http://, or not the address you opened (a proxy must pass Host and X-Forwarded-Proto)
Voice addressThe public IP the server tells browsers to send media to, and where it got itRed: it found none and no TURN is set: set WEBRTC_NAT_1TO1_IP. Amber: none, but a TURN relay is set
Voice portThe server listens for media on UDP 50000Red: the voice engine did not start (ports busy). Amber: WEBRTC_UDP_MUX_PORT=0 caps callers. Grey "Listening – not yet confirmed from outside" until a member from outside your network has connected, then green "Confirmed: a member from outside connected"
TURN relayThe built-in relay for networks that block UDPAmber: it could not bind port 3479, or is off with no external TURN (members behind strict networks cannot join). Grey "Not verified": the server could not reach its own relay port from inside, which a router without NAT loopback also causes although the forward works; run Test my connection from a phone on mobile data
Internet connectionWhether your line can receive forwarded portsShown only when there is a finding. Red: the WAN address is in 100.64.0.0/10 (CGNAT). Amber: no public IPv4 while IPv6 works (DS-Lite), or the host's own address differs from the one the internet sees. See Can I host at home?
WebSocketYour browser's live connection through the proxyGrey until a browser has connected; amber when browsers keep opening /api/ws without the upgrade headers: the proxy does not pass Upgrade and Connection
Reverse proxyRequests arrive from a trusted proxyThe proxy is not in TRUSTED_PROXY_CIDRS, or the setting is too broad
Outgoing mailSMTP is setOptional
Object storage, DatabaseThe containers answerA container is down or the secrets in .env do not match
Server clockThe host clock is rightTurn on NTP

Each item has stable check codes, such as voice_udp.unconfirmed or network.cgnat, listed with their meaning in operations.md.

Green does not prove that your router forwards UDP: the server cannot test that from inside. Use rungs 4 and 5.

Rung 4: Test my connection

Admin > Status > Test my connection runs in your browser. Open it from a network outside the server's (a phone hotspot, or the phone itself) and read the verdict: direct UDP works, only the relay works, or nothing works. "Only the relay works" means calls work but the UDP forward is missing or blocked: fix it (rung 5) so the relay is not the only way in. "Nothing works" means neither 50000-50050/udp nor 3479 reached the server: check the router and firewall, and CGNAT.

The last line of the result is the speed test: how fast this device downloaded from the server, and what that means for a screen share (roughly the server's upload, measured to the nearest reverse proxy or tunnel, so a tunnel in front of your server shows the tunnel's speed). It says it cannot measure when the device is on the server's network, so run it from the phone. Could not run means the stream was blocked or too short to mean anything. Too many speed tests is the limit of four per ten minutes per member (six per address): wait and repeat. Skipped because a Talk is running is on purpose: the test can fill a home uplink for three seconds, which would be heard in the call. In a terminal, docker compose exec app mnema-talk doctor prints the Status checks with the same fixes.

Rung 5: a real call between two networks

Join a Talk with a computer on Wi-Fi and a phone on mobile data (two members share one invite each). Expected: audio both ways within about two seconds. Two tabs on one computer test only the app, not your network; use them to rule the network out when there is no sound.

To test the TURN fallback, use a network that blocks UDP (a phone hotspot with a VPN on works) or read the selected pair in webrtc-internals below. If it works only there, direct UDP is blocked and the relay carries the call.

Reading chrome://webrtc-internals and about:webrtc

Browsers show their own view of a call. In Chrome, Edge and Opera open chrome://webrtc-internals (edge://webrtc-internals) in a new tab before you join the Talk; in Firefox open about:webrtc. Safari has no equivalent.

Each connection lists candidates, the addresses it can use:

TypeMeaning
hostThe device's own LAN address
srflxThe device's public address as seen through STUN
relayAn address on a TURN relay

Under the connection, the selected (nominated, succeeded) candidate pair shows what actually carries the media. How to read it:

  • Only host candidates: the browser got no answer from any STUN or TURN server; nothing outside the LAN can work. The server's address was probably not offered: check the announced address.
  • srflx candidates, but the call fails: the announced address (WEBRTC_NAT_1TO1_IP) is wrong, or UDP 50000-50050 is not forwarded.
  • Selected pair is relay: direct UDP failed and the relay carries it. Fine for one or two members; fix the forward so everyone does not depend on the relay.
  • Selected pair is srflx or host: direct UDP works.
  • The connection state failed means no candidate pair worked.

The logs

docker compose logs --since 10m app | grep -E 'webrtc announce|setup check|sfu ice|webrtc client diag'

On Synology without a shell: Container Manager > Container > mnema-talk > Log.

  • webrtc announce at startup shows the public IP the server tells browsers (and your LAN IP if you listed it), not only 172.x or 10.x addresses. If it shows only a private address, see "Works on the LAN, not outside" below.
  • sfu ice connected appears when a member's media path is up. Its remote_type is host, srflx or relay; a relay means that member came in through the TURN relay.
  • sfu ice failed or sfu ice disconnected, and a webrtc client diag line with "ice":"failed", mean packets from that member do not arrive. The diag line also lists the candidate types the browser gathered; no relay entry means no TURN server was on offer.
  • setup check: lines are the Status items, logged about twenty seconds after the start.
  • For more detail set LOG_LEVEL=debug, run docker compose up -d, reproduce the problem, then remove the line again.

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 – reconnecting…"The proxy does not pass WebSocketsEnable WebSockets
403 on sign-in or on every requestPUBLIC_URL does not match the address in the browser (scheme, host and port)Set 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 proxy address named in Status > Reverse proxy into TRUSTED_PROXY_CIDRS
No sound even on the same LANMicrophone permission, wrong input device, a silent microphoneBrowser site settings and the in-app audio settings; test two tabs on one computer to rule the network out
Works on the LAN, not from outsideUDP 50000-50050 not forwarded, host firewall, wrong announced addressForward the whole range to the host's LAN address, open the host firewall, check webrtc announce
Works from outside, not on the LANThe router has no NAT loopbackSet WEBRTC_LAN_IP=192.168.1.20 (the server's address in your network; the setup assistant asks for it), or list it after the public one: WEBRTC_NAT_1TO1_IP=203.0.113.7,192.168.1.20; or use split-horizon DNS
Nobody outside ever connects, though ports are forwardedCGNAT or DS-Lite: your line has no public IPv4Can I host at home?; move to a VPS
Connects, then drops after secondsWrong announced address, or only part of the range forwardedCheck webrtc announce; forward the whole range
One person cannot join, the others canTheir network blocks UDP (company, VPN, Opera VPN or WebRTC protection)Forward 3479 on UDP and TCP, run the probe, try another network
One person behind a strict network fails to join after many quick rejoins or with many tabs openThe built-in relay's per-member limits: 4 relay sessions at once, 60 started in a burst and 2 a second after that (limits); mnema_turn_events_total shows rate_limited or quota_userClose spare tabs and devices, wait a few seconds and join again; running calls are not affected, and other members are not limited by this one
Wrong WEBRTC_NAT_1TO1_IPA typo, a stale dynamic-DNS name, or only the LAN IP setUse the public IP or a current dynamic-DNS name, plus the LAN IP; check with curl -4 https://ifconfig.me from the server's network
A port stays closed although forwardedThe host firewall (ufw, DSM) or a cloud security group blocks UDP 50000-50050 or 3479Open them in both places (platform notes)
The desktop client shows a connection errorSee the tableDesktop client errors

More on announced addresses, IPv6 and coturn: operations.md.

Probe the TURN relay from outside

scripts/turn-probe.py (standard library only) checks from another network that the relay answers on UDP and TCP. Copy the file from the repository, run it outside your network (a VPS or a phone hotspot with a laptop), and give the target in the environment:

TURN_PROBE_HOST=chat.example.com python3 turn-probe.py            # port 3479 by default
TURN_PROBE_HOST=chat.example.com TURN_PROBE_PORT=3479 python3 turn-probe.py --attempts 3

For each transport (UDP and TCP) it sends a STUN request and an unauthenticated TURN allocation and ends with RESULT udp: PASS and RESULT tcp: PASS, or FAIL. A pass means the relay answered on that protocol. A FAIL on one protocol only means you forwarded just the other one; FAIL on both means the forward, the firewall or the host name is wrong. The script prints neither your host name nor any address it resolved.

Something wrong on this page? Tell us.