Troubleshooting Guide

Solutions for common rVPN 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/api/v1/ws

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

WebSocket path is correct. Clients connect to {websocket_path} (e.g., /api/v1/ws). If your server uses a different path, update client.toml.

”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 rvpn-server

Wrong hostname in server_address:

# The hostname must match the certificate
server_address = "wss://your-server.com/api/v1/ws"  # Certificate must be for your-server.com

SNI mismatch:

# If connecting through a CDN or by IP
server_address = "wss://10.0.0.1/api/v1/ws"
sni_hostname   = "your-server.com"  # Certificate hostname

iOS: Cert verification issue (older builds): Ensure you have rebuilt the Rust library after updating. rVPN’s TLS stack uses BoringSSL with a bundled Mozilla CA root store and does not consult the iOS keychain, so certificate rotations or trust changes at the OS level don’t apply until the app is rebuilt.

”Connection refused” immediately

Symptoms: Client fails instantly with Connection refused.

Check:

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

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

# Can you connect locally? (uses whatever bind_address is set to)
curl -I https://127.0.0.1:443/api/v1/ws --insecure

“X3DH handshake failed”

Symptoms: Connection starts but fails during encryption setup.

Causes:

Prekey bundle mismatch: Clients and servers must use the same prekey bundle. If the server rotated keys and the client has an old bundle, this can fail.

# On server: regenerate prekey bundle
rvpn-server prekey-bundle
# Distribute new prekey-bundle.json to clients

Identity key changed: If the server identity key was regenerated, all clients need the new prekey bundle.

”Too many connections” or rate limit exceeded

Symptoms: Connection refused or Rate limited after connecting successfully for a while.

Check server rate limits:

[server.rate_limit]
max_connections_per_ip    = 500      # default
max_handshakes_per_minute = 2000     # default

Each client connection consumes one slot. Defaults are generous — if you have a very large fleet on a single egress IP, raise these; if you’re being probed and want tighter limits, drop them.

TUN Mode Problems

Client connects but has no internet access

Check 1: IP forwarding on server:

sysctl net.ipv4.ip_forward
# Must return: net.ipv4.ip_forward = 1

If not enabled:

sudo sysctl -w net.ipv4.ip_forward=1
echo "net.ipv4.ip_forward = 1" | sudo tee -a /etc/sysctl.conf

Check 2: NAT rules on server:

sudo iptables -t nat -L POSTROUTING -v
sudo iptables -L FORWARD -v

You should see MASQUERADE rules and FORWARD ACCEPT rules.

If missing:

sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
sudo iptables -A FORWARD -i tun0 -o eth0 -j ACCEPT
sudo iptables -A FORWARD -i eth0 -o tun0 -m state --state RELATED,ESTABLISHED -j ACCEPT

Check 3: Server security group/firewall allows outbound: The server must be able to initiate outbound connections to any IP on any port for NAT to work.

Check 4: NAT enabled in server.toml:

[server.network]
nat_enabled = true

Check 5: Client routes:

# On client, check routing table
ip route show  # Linux
route -n get 0.0.0.0  # macOS

# Default route should point to tunnel interface

Traffic flows out but nothing returns

Symptoms: You can ping external IPs but get no response. Server logs show frames being relayed but no “Relay completed”.

Root cause: SOCKS5 response sent before tunnel was ready.

Fix: This was a bug in older versions. Rebuild and redeploy:

cd rvpn-ios && ./build_rust.sh

Check server logs:

INFO  rvpn_server: Listening on 0.0.0.0:443
INFO  rvpn_server: WebSocket path: /api/v1/ws
INFO  rvpn_server: TUN mode enabled

If TUN mode is not enabled, clients in TUN mode will fail to connect properly.

TUN interface not created on server

Check:

sudo ip addr show tun0
sudo ip link show tun0

If interface does not exist:

Verify enabled = true in [server.tun]
Check server logs for errors during interface creation
Try a different interface name in case of naming conflict

Client cannot ping server TUN IP

Check:

# On server
ping 10.200.0.1  # From server to itself via tun0

# On client
ping 10.200.0.1  # Client should be able to reach server's TUN IP

If client cannot reach 10.200.0.1, the tunnel is not established properly.

SOCKS5 Mode Problems

Apps not routing through proxy

Check 1: Proxy is running:

curl --socks5 127.0.0.1:1080 https://api.ipify.org

If this returns your VPN server IP, the proxy is working.

Check 2: System proxy settings: Ensure your system or app is configured to use 127.0.0.1:1080 as SOCKS5 proxy.

Check 3: Browser proxy settings: Chrome and Edge use system proxy settings. Firefox has its own proxy settings.

Check 4: App-specific issues: Some apps do not support SOCKS5 (only HTTP proxy). Use a SOCKS5-to-HTTP proxy adapter or switch to TUN mode.

DNS leaks in SOCKS5 mode

Symptoms: DNS leak test shows your ISP DNS, not VPN DNS.

Fix: Enable the DNS proxy:

[dns_proxy]
enabled        = true
listen_address = "127.0.0.1:53"

Configure your system DNS to 127.0.0.1. See DNS Leak Prevention for detailed setup.

Chrome-specific issue: Chrome uses its own secure DNS resolver by default, which bypasses the system DNS and the VPN tunnel.

On desktop/Android: Go to Settings → Privacy and security → Security → Use secure DNS and turn it off.
Clear Chrome’s DNS cache: visit chrome://net-internals/#dns and click Clear host cache.
On iOS: Force-close Chrome or clear browsing data to flush its cache.

Connection-per-flow limits (multiplex trade-off)

multiplex defaults to false — the standard, recommended mode — because one-WebSocket-per-flow blends in with the traffic pattern of normal browsing and evades multiplex-shape DPI classifiers. The trade-off is that a busy browser can open dozens of concurrent WebSockets and, on shared egress IPs, hit the server’s max_connections_per_ip limit.

Two ways to handle it:

Ask your server administrator to raise the defaults:

[server.rate_limit]
max_connections_per_ip    = 1000
max_handshakes_per_minute = 5000

Enable multiplex on the client to share a single tunnel across all flows (lower latency, but a more distinctive traffic pattern):
```
[socks5]
multiplex = true
```

Slow connection speeds

Possible causes:

High latency: The VPN server is geographically distant
Server overload: Too many connections to one server
Bandwidth limit: Server’s upstream is saturated
MTU issues: Packet fragmentation on high-latency links

Solutions:

Lower MTU in client.toml:

[tun]
mtu = 1280

Try a different server closer to your location
Check server load: uptime, htop
Disable IPv6 if not needed:

[network]
ipv6_enabled = false
prefer_ipv4  = true

iOS App Problems

”Failed to start VPN”

Check:

Server address includes wss:// (not https://)
Identity key is generated (Settings -> Identity)
Prekey bundle is imported
Server is running and accessible

Rebuild Rust library:

cd rvpn-ios && ./build_rust.sh

Connection drops frequently

Possible causes:

Network instability (Wi-Fi to cellular handoff)
iOS suspending the app in background
VPN profile being revoked

Solutions:

Enable “Always-on VPN” in iOS Settings -> VPN
Check for iOS updates
Rebuild and reinstall the app

No IP assigned

Cause: The server’s DHCP pool is exhausted.

Fix: Increase the DHCP range on the server:

[server.network]
dhcp_range = "10.200.0.0/22"  # /22 gives 1022 IPs instead of 254

Or disconnect unused clients.

macOS App Problems

VPN stops working after an app update

Symptoms: The app shows “Connected” but no traffic passes, or the connection fails immediately after updating from the App Store or rebuilding from Xcode.

Cause: macOS persists VPN profiles in System Settings independently of the app. After an update, the stored profile’s tunnel extension reference becomes stale because the extension’s code signature has changed. The app tries to start the old extension, which no longer exists.

Fix:

Open System Settings > VPN (or System Settings > General > VPN & Filter on newer macOS versions).
Delete the rVPN entry.
Re-open the rVPN app and reconnect. The app will create a fresh profile automatically.

This is resolved in version 1.2.4 and later, which automatically detects and replaces stale profiles on launch.

”Failed to start VPN” or connection fails silently

Check:

Open the rVPN app and go to Settings (Cmd+,). Verify the profile shows green checkmarks for both Identity Key and Prekey Bundle.
Server address must start with wss:// and have no trailing whitespace.
The server must be running and accessible on port 443.

If the profile is missing keys:

Generate a new identity key in the profile editor.
Import the prekey bundle from your server administrator.

If keys are present but it still fails:

Delete the VPN profile from System Settings > VPN.
Delete the rVPN app.
Reinstall from the App Store.
Reconfigure the profile and reconnect.

Tunnel connects but DNS does not resolve

The macOS app runs a local DNS proxy for split-tunnel DNS resolution. If DNS fails:

Check that the server address is reachable from your network.
Try disabling split tunnel in the profile editor to test full-tunnel mode.
Check server logs for DNS proxy errors.

How to collect diagnostic logs

Rust-level logs (bypasses macOS log redaction):

cat ~/Library/Group\ Containers/group.org.rvpn.client/rvpn_tunnel_rust.log

System-level logs (may be redacted on macOS 12+):

log show --predicate 'subsystem == "org.rvpn.tunnel"' --last 5m --level debug

Console.app can also be used: filter by subsystem org.rvpn.tunnel.

Split Tunnel Problems

Bypassed traffic still going through VPN

Check:

[split_tunnel]
enabled = true  # Must be true for any bypass to work
builtin_bypass_countries = ["CN"]

Verify rules are loaded: The client logs should show bypass rules on startup:

INFO  rvpn_client: Split tunnel enabled, X networks bypassed

Check routing table:

ip route show  # Linux
route -n get 0.0.0.0  # macOS

Ensure bypassed networks are not in the VPN routing table.

Streaming service still blocking

Causes:

Streaming services may use GPS/locale signals, not just IP
Account payment currency and history affect content
CDN IPs may not match country bypass data

Solutions:

Clear browser/app cookies and cache
Use a browser extension to spoof timezone and locale
Full tunnel mode may be needed (bypass nothing)

Performance Problems

High latency through VPN

Check latency to server:

ping your-server.com

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

Optimise:

Use a server closer to your location
Lower MTU if on satellite or high-latency link:

[tun]
mtu = 1280

Low throughput

Check:

Server bandwidth: iperf3 test to server
Client hardware: encryption is CPU-intensive on older devices
Network congestion

Optimise:

[performance]
worker_threads        = 4
crypto_worker_count   = 4
recv_buffer_size      = 262144
send_buffer_size      = 262144

Getting More Information

Enable debug logging

For detailed client logs:

RUST_LOG=debug rvpn -c ~/.config/rvpn/client.toml

For server logs:

RUST_LOG=debug sudo rvpn-server -c /etc/rvpn/server.toml

Check system logs

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

# kernel logs (for TUN interface issues)
dmesg | grep tun

Verify network paths

# Trace path to server
traceroute your-server.com

# Trace path from server to target
# (on server) sudo tcpdump -i tun0 -n

Common log messages

Log message	Meaning
`Listening on 0.0.0.0:443`	Server started successfully
`WebSocket path: /api/v1/ws`	WebSocket endpoint configured
`TUN mode enabled`	Server TUN interface active
`X3DH handshake complete`	Encryption established
`NAT enabled`	Server will masquerade client traffic
`Relay completed`	One data relay session finished
`Too many connections`	Rate limit exceeded