Troubleshooting

Installation warnings

Windows SmartScreen blocks the installer

Windows SmartScreen may show "Windows protected your PC" when running the installer. This happens because the app is not yet signed with an EV code signing certificate. Click More info → Run anyway.

If the option doesn't appear, your organization may have a Group Policy blocking unsigned apps. In that case, build from source instead.

macOS says the app cannot be checked

Released macOS builds are code-signed and notarized, so this should not happen. If it does, you are most likely running a build you compiled yourself, or one that did not come from the releases page.

For a local build, right-click the app → Open → confirm Open, which is remembered for future launches. For something you downloaded as a release, please report it rather than clicking through: a notarized app failing this check is worth knowing about.

Linux AppImage won't launch

The AppImage may not have the execute permission set after download:

chmod +x Gryt-Chat-*.AppImage
./Gryt-Chat-*.AppImage

Update issues

Profile resets on every launch or update

If you have to set up your profile every time you launch or update Gryt, the likely cause is a stale installation from before version 1.0.122. In that release the Electron package name was changed from client to gryt-chat, which moved the install directory from C:\Users\<user>\AppData\Local\Programs\client to C:\Users\<user>\AppData\Local\Programs\gryt-chat. The old installation still exists at the previous path and conflicts with the new one, so profile and settings data does not persist between launches.

To fix this:

Fully uninstall the Gryt client (Settings → Apps → Gryt Chat → Uninstall).
Delete any leftover C:\Users\<user>\AppData\Local\Programs\client folder if it still exists.
Download and install the latest version from gryt.chat.

Connection issues

WebSocket connection fails

curl http://localhost:5000/health    # server
curl http://localhost:5005/health    # SFU

Verify ports 5000 and 5005 are not blocked by a firewall. Both are TCP, and neither carries voice — if chat works and audio does not, it is the UDP media port instead, covered under nobody can hear anyone
Check CORS: CORS_ORIGIN in server/.env must include http://127.0.0.1:15738 (desktop app), https://app.gryt.chat (web client), and any custom client origins
In production, ensure WSS (not WS) is used

Server clock is wrong

If joining fails with a message about the server's clock, the two machines disagree about the time by more than a minute.

A server proves who it is by signing a short statement, good for 60 seconds. Your client checks it has not expired. When the server's clock is off, a proof it signed a moment ago looks like one signed minutes ago, and the client refuses it. Nothing is wrong with the server's identity and nothing is being attacked. The clock is just wrong.

Gryt tells you which way and by how much, so a message saying the server is four minutes behind you means the server is the one to fix.

On the server:

timedatectl

You want System clock synchronized: yes. If it says no, or NTP service: n/a, the machine has no time sync running. Fresh VPS images often ship without it:

apt update && apt install -y chrony
timedatectl

chrony corrects the clock on startup rather than drifting slowly into place, so the next join works immediately. No need to restart Gryt, since the proof is signed from the clock at the moment it is asked for.

If timedatectl set-ntp true answers NTP not supported, that is the same thing: systemd-timesyncd is not installed. Installing chrony above fixes it, or install systemd-timesyncd and enable it instead.

Container hosts inherit the clock from the machine underneath, so fix it there rather than inside the container.

"Server identity not recognised"

The server answering at this address presented a different identity key than the one pinned when you first joined, so Gryt refused the connection before sending anything.

Almost always this means the server was rebuilt or reinstalled without preserving its data directory, so it generated a new identity. Confirm by checking the server's startup log, which prints its key on boot:

docker compose logs server | grep "identity key"
# ✔ Server identity key ready (85lc28xWNMb-UkGlcc_kDowxgGHaeLKSYI0jVaKyTq4)

Compare that to the fingerprint under Settings → You → Server identities. If it matches, unblock the server there and reconnect.

If it does not match, something else is answering at that address. Do not unblock it.

To avoid this when moving or rebuilding a server, keep server-identity-key.json from the server's DATA_DIR — see Security.

People connect and chat, but nobody can hear anyone

This is the signature of a wrong or unreachable advertised address, and it is worth recognising because nothing in the app will say so.

Chat and voice do not travel the same way. The signalling connection uses the address people joined on, so if they can see the server and send messages, that address is fine. Media does not use it: WebRTC connects directly to whatever the SFU advertises, which is ICE_ADVERTISE_IP and SFU_PUBLIC_HOST. Get those wrong, or leave the UDP port closed, and everything except the audio works.

So the fault does not look like a network problem. It looks like broken audio.

Check, in this order:

ICE_ADVERTISE_IP is your real public IP, not the machine's LAN address. A server behind NAT cannot discover this by looking at itself.
ICE_UDP_MUX_PORT is open and forwarded to the SFU host. There is one media port and it is UDP, 3478 unless you set ICE_UDP_MUX_PORT to something else.
The forward points at the machine running the SFU, which is not necessarily the machine running the server.

Testing this from the server itself proves nothing. Some routers will let a machine reach its own public IP and some will not, and neither answer tells you what somebody outside your network sees. It has to be tried from outside, by somebody on a different connection or on mobile data with Wi-Fi off.

SFU connection fails

wscat -c ws://localhost:5005

Verify STUN servers are reachable: dig stun.l.google.com
Ensure ICE_UDP_MUX_PORT is open as UDP. All media shares that one port
Check the SFU actually started. It binds the mux port at boot and exits if something else holds it, logging failed to create ICE UDP mux on port
curl -s localhost:5005/health — a 503 with "status":"starting" means its UDP readiness probe has not passed yet
If you use Cloudflare Tunnel / Cloudflare proxy for the SFU WebSocket, remember WebRTC media is still direct UDP to the SFU host — set ICE_ADVERTISE_IP to your real public IPs and open the UDP port(s) there
Verify the SFU hostname DNS record is set to Proxied (orange cloud) in Cloudflare — a grey-cloud (DNS-only) record won't route through the tunnel
Review SFU logs: docker compose logs sfu

Audio issues

Microphone not working

Check browser permissions (chrome://settings/content/microphone)
WebRTC requires HTTPS in production
Try a different browser or audio device

Poor quality / echo

Use headphones to avoid feedback loops
Adjust the noise gate threshold in audio settings
Ensure echoCancellation and noiseSuppression are enabled (default)

On the desktop app (Windows/macOS), Gryt automatically excludes its own audio from the screen share capture using OS-native APIs. If this is not working:

Windows: Requires Windows 10 build 20348 or later. Check with winver.
macOS: Requires macOS 13.0 (Ventura) or later.
If the native binary is missing, the feature is silently unavailable. Rebuild with npm run build:native or reinstall the app.

On the web client and Linux desktop app, there is no OS-level API to separate Gryt audio from other system audio. Your options:

Use headphones so Gryt voice audio is not picked up by the screen capture.
Route Gryt to a separate audio output device (virtual audio cable) and share only your main output.

Audio cutting out

Check network stability
Review SFU logs for connection state changes
See the Voice Debugging guide

Server restart / reconnection

Voice shows "Unknown" user after restart

This was fixed in the latest release. The root cause was a race condition where clients would re-join with a stale local nickname before the server finished restoring their session from the JWT. Ensure you are running the latest server and client versions.

Voice activity indicators missing after restart

Gryt now performs a full SFU disconnect and reconnect when the signaling server comes back online. This cleanly re-establishes stream mapping, speaking indicators, and member list voice status. The reconnect takes roughly 2–3 seconds after the server is available again.

docker compose logs
docker stats

Check for port conflicts: netstat -tulpn | grep :5000
Rebuild: docker compose down; docker compose build --no-cache; docker compose up -d

High resource usage

# Limit resources in compose
services:
  server:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'

Kubernetes issues

Pods stuck or crashing

kubectl get pods -l app.kubernetes.io/name=gryt
kubectl describe pod <pod-name>
kubectl logs <pod-name>

Services not reachable

kubectl get services -l app.kubernetes.io/name=gryt
kubectl get ingress

Debug logging

DEBUG=gryt:* npm run dev          # all components
DEBUG=gryt:audio:* npm run dev    # audio only
DEBUG=gryt:websocket:* npm run dev

Health and metrics endpoints

Endpoint	Service	Description
`GET /health`	server, SFU	Health check
`GET /metrics`	server, SFU	Prometheus metrics

Reporting issues

For feature requests, use feedback.gryt.chat.

When opening a bug report on GitHub Issues, include:

OS, browser, and Docker/K8s version
Sanitized environment variables
Server and browser console logs
Steps to reproduce