Troubleshooting

Common problems and their solutions when running a Freedom Messenger server.

Server Will Not Start

Port already in use

Another process is using port 443 (or your configured port). Find it and stop it:

sudo lsof -i :443
sudo systemctl stop nginx   # if nginx is using 443

Permission denied on port 443

The binary needs the CAP_NET_BIND_SERVICE capability to bind to ports below 1024:

sudo setcap cap_net_bind_service=+ep /opt/freedom-mess/freedom-mess

Config file permission error

The server requires config.toml to have 0600 permissions:

chmod 600 /opt/freedom-mess/config.toml

Database integrity check failed

The database may be corrupted. Restore from your most recent backup. See Backup & Recovery.

TLS Certificate Issues

Certificate not issued (HTTPS mode)

Let's Encrypt needs to verify your domain. Check:

  • Port 80 is open (used for HTTP-01 challenge)
  • Domain A record points to this server's IP
  • No other service is listening on port 80
  • DNS propagation is complete (dig your-domain.com)

Certificate expired

Certificates auto-renew. If renewal failed, restart the server — it will attempt renewal on startup. Check logs for ACME errors.

Connection Problems

WebSocket disconnects

If users experience frequent disconnections:

  • Check server memory — if the 512 MB limit is reached, the systemd OOM protection may restart the service
  • In Cloudflare mode, ensure Cloudflare's WebSocket support is enabled (it is by default)
  • Check for proxy or firewall rules that terminate idle connections

Cloudflare 524 timeout

Cloudflare returns 524 when the origin server does not respond within 100 seconds. Check that the server is running and listening on port 8080.

Voice Call Issues

Calls do not connect

  • Ensure UDP port 3478 is open in your firewall
  • Verify public_ip in config.toml is correct
  • Check that both users have granted microphone permission

One-way audio

Usually caused by incorrect public_ip or asymmetric NAT. Verify the public IP matches what external services see for your server.

Performance

High memory usage

Normal idle usage is 30-80 MB. If memory grows beyond 200 MB:

  • Check the number of active WebSocket connections in the admin dashboard
  • Check goroutine count — abnormally high numbers may indicate a leak
  • Restart the server to reclaim memory

Slow database queries

SQLite uses WAL mode for performance. If queries are slow:

  • Check disk I/O — SQLite performance depends on disk speed
  • The server runs hourly WAL checkpoints — check logs to confirm they are completing
  • Consider moving to an SSD if you are on a spinning disk

Getting Help

If your problem is not listed here:

  1. Check the server logs: sudo journalctl -u freedom-mess -f
  2. Check the admin dashboard logs (filter by error level)
  3. Open an issue on GitHub with the error messages and your server configuration (redact secrets)