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 Gatekeeper blocks the app

macOS shows "can't be opened because Apple cannot check it for malicious software". Right-click the app → Open → confirm Open. This bypass is remembered for future launches.

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
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

SFU connection fails

wscat -c ws://localhost:5005

Verify STUN servers are reachable: dig stun.l.google.com
If using ICE UDP mux (ICE_UDP_MUX_PORT), ensure UDP 443 (or your chosen mux port) is open
Otherwise, ensure the SFU UDP port range is open (ICE_UDP_PORT_MIN / ICE_UDP_PORT_MAX)
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