Troubleshooting guide

Solutions for common rChat problems.

Connection problems

“Failed to connect” or timeout

Symptoms: The client hangs at Connecting to wss://... and eventually times out.

Check:

Server port is accessible:

# From a different machine
nc -zv your-server.com 443
curl -I https://your-server.com

Firewall allows port 443:

sudo ufw status  # UFW
sudo iptables -L -n | grep 443  # iptables

TLS certificate is valid:

openssl s_client -connect your-server.com:443 -servername your-server.com </dev/null 2>/dev/null | openssl x509 -noout -dates

“TLS handshake failed”

Symptoms: Client shows TLS handshake failed or certificate verify failed.

Causes and solutions:

Let’s Encrypt certificate not renewed:

sudo certbot certificates
sudo systemctl reload rchat-server

Wrong hostname in server address:

# The hostname must match the certificate
wss://your-server.com  # Certificate must be for your-server.com

SNI mismatch:

# If connecting through a CDN or by IP
wss://10.0.0.1
# Set SNI hostname separately in client settings

“Connection refused” immediately

Symptoms: Client fails instantly with Connection refused.

Check:

# Is the server running?
sudo systemctl status rchat-server

# Is it listening on the right port?
sudo ss -tlnp | grep 443

# Can you connect locally?
curl -I http://127.0.0.1:8443

“Session not established”

Symptoms: Connection succeeds but messages cannot be sent.

Causes:

Contact has not published their key: Both parties must publish their public key bundle to the server before starting a conversation.
Wrong identity key: Verify the contact’s identity key is correct. A single character error will prevent the handshake.
Server restart: If the server restarted without message_queue_persist_path, queued messages are lost. Re-initiate the conversation.

Server problems

High memory usage

Check connection count:

curl -s http://localhost:9090/metrics | grep rchat_connections_total

Check for memory leaks:

# Restart the server as a temporary measure
sudo systemctl restart rchat-server

Connection limits

Check current limits:

ulimit -n

Increase limits:

ulimit -n 1000000

Permanent change: Add to /etc/security/limits.conf:

* soft nofile 1000000
* hard nofile 1000000

iOS and macOS app problems

“Failed to connect”

Verify server address is correct and includes wss:// (not https://)
Ensure identity key is generated
Ensure the server is running and accessible

“Session not established”

Verify the contact’s identity key is correct
Ensure the contact has published their key to the same server
Try starting the conversation again

Connection drops frequently

Possible causes:

Network instability (Wi-Fi to cellular handoff)
iOS suspending the app in background
Server instability

Solutions:

Enable Background App Refresh for rChat in iOS Settings
Check for iOS/macOS updates
Verify your server is stable

CLI client problems

“Identity key not found”

Run rchat-cli keygen first, or specify the path:

rchat-cli --identity-key ~/.config/rchat/identity.key

“Permission denied”

Ensure the binary is executable:

chmod +x /usr/local/bin/rchat-cli

On macOS, you may also need to remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/rchat-cli

Performance problems

High latency

Check latency to server:

ping your-server.com

If latency is high even to the server, the issue is geographic distance, not rChat.

Optimise:

Use a server closer to your location
Check server load: uptime, htop

Low throughput

Check:

Server bandwidth
Client hardware: encryption is CPU-intensive on older devices
Network congestion

Optimise server:

[server]
rate_limit_bps = 10485760  # Increase to 10 MB/s

Getting more information

Enable debug logging

For detailed client logs:

RUST_LOG=debug rchat-cli --server wss://your-server.com

For server logs:

RUST_LOG=debug sudo rchat-server --config /etc/rchat/server.toml

Check system logs

# systemd journal
sudo journalctl -u rchat-server -f

# kernel logs
sudo dmesg | grep -i tcp

Verify network paths

# Trace path to server
traceroute your-server.com

# Check server listening ports
sudo ss -tlnp

Common log messages

Log message	Meaning
`Listening on 0.0.0.0:443`	Server started successfully
`WebSocket endpoint ready`	WebSocket handler is active
`Metrics endpoint: 0.0.0.0:9090`	Prometheus metrics are available
`X3DH handshake complete`	Encryption established with a contact
`Circuit created`	A new relay circuit has been set up
`Rate limited`	A client exceeded the per-circuit bandwidth limit