Skip to content
RayTun

Troubleshooting

Solutions for common V2RayTun issues — node connectivity, TLS errors, protocol problems, and more.

Panel Won't Start

Symptoms

v2raytunsetup status shows one or more services as Exit or Restarting.

Steps

  1. Check logs for the failing service:
Bash
v2raytunsetup logs backend
  1. Port conflict — ensure ports 80 and 443 are not used by another process:
Bash
ss -tlnp | grep -E ':80|:443'
  1. Database connection — if the backend fails with a PostgreSQL error, verify the database container is healthy:
Bash
docker compose exec postgres pg_isready
  1. Restart all services:
Bash
v2raytunsetup restart

Node Shows Offline

Check mTLS Certificates

The most common cause is a certificate mismatch. Re-download certificates from the panel:

  1. Go to Nodes → Select Node → Certificates.
  2. Copy the new ca.crt, node.crt, node.key to the node server.
  3. Restart the node: docker compose restart.

Check Connectivity

Ensure the node can reach the panel on port 62050:

Bash
curl -v https://panel.example.com:62050

Check Firewall

Verify that port 62050 is open on both the panel and the node.

TLS Certificate Not Issuing

Caddy uses Let's Encrypt for automatic TLS. If certificates fail to issue:

  1. Verify DNS — both domains must resolve to the panel server's IP:
Bash
dig +short panel.example.com
dig +short sub.example.com
  1. Ensure ports 80 and 443 are reachable from the internet.
  2. Check Caddy logs:
Bash
docker compose logs caddy
  1. If rate-limited by Let's Encrypt, wait and retry in 1 hour.

VLESS Reality Not Connecting

  • Verify the SNI domain is accessible from the client's network (some ISPs block certain domains).
  • Try changing the SNI to another popular domain (e.g., www.microsoft.com).
  • Ensure the client's fingerprint setting matches the host configuration.
  • Confirm port 443/TCP is open on the node.

AmneziaWG Not Connecting

  • Verify the amneziawg kernel module is loaded:
Bash
lsmod | grep amneziawg
  • If missing, install kernel headers and rebuild:
Bash
apt install -y linux-headers-$(uname -r) amneziawg-dkms
  • Ensure port 51820/UDP is open.

Hysteria2 Not Connecting

  • Confirm port 8443 is open for both TCP and UDP.
  • Check that the client supports Hysteria2 (v2rayNG 1.9+, Hiddify).
  • Verify the obfuscation password matches between server and client.

Subscription Returns Empty

  • Verify the user's Squad has hosts assigned.
  • Check that the subscription domain DNS resolves correctly.
  • Ensure the backend service is running: v2raytunsetup status.

Collecting Logs for Support

Bash
v2raytunsetup logs > /tmp/v2raytun-logs.txt 2>&1

Share the log file when reporting issues.