Troubleshooting & Logs
Where to look when something breaks, and what to collect so a bug report is actionable on the first read.
Where logs live
Desktop client
| Platform | Path |
|---|---|
| Windows | %APPDATA%\speakeasy-im\logs\ |
| Linux | ~/.config/speakeasy-im/logs/ |
If the app fails to launch at all, also grab startup-diag.txt in the folder above logs\. Client logs are scrubbed of passwords, tokens, and session identifiers before being written, so they are safe to attach to a report.
Server
- Linux (guided install):
journalctl -u speakeasy-self-host, plus files under/var/lib/speakeasy-self-host - Windows (packaged install):
%ProgramData%\SpeakeasySelfHost\logs\
Do not open, inspect, or repair the server database with your operating system's sqlite3 tool: older versions report its schema as malformed even though the database is healthy. To keep a copy, follow the backup steps.
Every bug report should include
- Client version and server version
- OS (and for Linux: distribution + X11 or Wayland)
- What you expected, what happened instead, and steps to reproduce
- The relevant log files above
- For voice/screen-share issues: hardware (mic model / GPU + driver version), and whether the problem is window shares, monitor shares, or both
Can't connect to a server
- DNS: does the server's domain resolve to the right public IP? (
nslookup yourdomain) - Port: is the HTTPS port (usually 443) reachable from outside? Test from a phone off wifi if unsure — router "hairpin NAT" can make a server reachable from the internet but not from its own LAN by domain name.
- Certificate: a newly installed server needs port 80 open to obtain its TLS certificate; check the server log for certificate errors.
- Server up:
systemctl status speakeasy-self-hoston the host.
Voice connects but no audio flows
Signaling uses the HTTPS port, but voice media uses the WebRTC media port (UDP). If you can join a room but hear nothing, the media port almost certainly is not forwarded, or UDP is blocked. Check the ports table and your router's forwarding rules.
Microphone problems
- Check the input device selected in Speakeasy's audio settings matches the mic you're using.
- Check the OS-level privacy/permission settings allow microphone access.
- Push-to-talk not working when unfocused → push-to-talk guide (Linux input permissions live there).
Screen share problems
See the dedicated notes in the screen share guide — black frames, Wayland portal requirements, and performance data to collect.
Install problems
- Windows client: SmartScreen warnings are expected — see why. If the installer fails outright, note the exact error and your Windows version.
- Linux client: AppImage needs
chmod +x; if it fails to start, run it from a terminal and capture the output. - Server: the installer waits for a health check — if it times out, read the service journal; nine times out of ten it is certificate issuance (port 80 / DNS) rather than the server itself.
Reporting
Bugs and support: reach out via Patreon or X. Security issues: responsible disclosure — privately, please.