vpn-troubleshoot

name	vpn-troubleshoot
description	VPN troubleshooting decision tree. Use when user reports VPN problems: 'VPN not working', 'can't connect', 'stopped working', 'no internet through VPN', 'slow VPN', 'troubleshoot'. Also use when deployment fails.

VPN Troubleshooting

Decision tree for diagnosing and fixing VPN infrastructure problems. For beginners — specific commands and solutions, not abstract methodology.

When to Use

Use when the user reports ANY VPN problem:

• "VPN not working", "can't connect", "stopped working"
• "No internet", "slow speed", "works on Wi-Fi but not LTE"
• Deployment script failed
• Any error message related to VPN

The Iron Law

DIAGNOSE BEFORE FIXING. RUN THE COMMAND BEFORE CLAIMING THE RESULT.

Never suggest a fix without first running diagnostics. Never claim "fixed" without verifying.

Decision Tree

Step 1: Can we SSH to the server?

Run: python ssh_exec.py status

Result	Diagnosis	Action
Success (shows xray info)	SSH works	Go to Step 2
"Connection refused"	Port blocked or SSH not running	Go to Branch A
"Authentication failed"	Wrong credentials	Go to Branch B
"Connection timed out"	VPS down or IP wrong	Go to Branch C
"No such file: .env"	Missing config	Tell user to create .env from .env.example

Branch A: Connection Refused

1. Check current SSH port in .env (VPN_SSH_PORT)
2. If port is 22: TSPU often blocks port 22 to foreign IPs
   • Change VPN_SSH_PORT=49152 in .env
   • Retry python ssh_exec.py status
3. If port is 49152 and still refused:
   • VPS firewall may block it, or SSH service is down
   • Ask user to log into VPS provider's web console and check

Branch B: Authentication Failed

1. Check .env for VPN_SSH_KEY and VPN_SSH_PASS
2. If using key: verify the key file exists at the specified path
3. If using password: ask user to verify password is correct (no extra spaces)
4. Common issue: key is for a different server (user changed VPS but kept old key)

Branch C: Connection Timed Out

1. Ask user: "Is your VPS running? Check in your provider's dashboard."
2. Try ping: ping -c 3 <VPN_HOST from .env>
3. If ping works but SSH doesn't: firewall blocks SSH port
4. If ping fails: VPS is down, IP is wrong, or ISP blocks the IP entirely

---

Step 2: Is xray running?

From ssh_exec.py status output, check xray process status.

Result	Action
xray: "running"	Go to Step 3
xray: "stopped" or not found	Restart: python ssh_exec.py restart
After restart still not running	Check logs: python ssh_exec.py logs

Common log errors:

• "failed to read config" — corrupted xray config. Re-deploy: python ssh_exec.py deploy quick-rebuild.sh
• "address already in use" — port conflict. Run: python ssh_exec.py exec "ss -tnlp | grep -E '443|8443|2053'"
• "certificate not found" — SSL cert missing. Re-deploy will regenerate it

---

Step 3: VPN connects from client?

Ask user: "Does your VPN client (v2rayN/Shadowrocket/v2rayNG) show 'Connected'?"

Result	Action
Yes, connected	Go to Step 4
No, cannot connect at all	Go to Branch D
Connects then disconnects	Go to Branch E

Branch D: Client Cannot Connect

1. Check which port: ask which VLESS URI the user imported (port 443, 8443, or 2053)
2. Try another port:
   • If using 443, try 8443 or 2053
   • Each port uses a different SNI (microsoft.com, google.com, apple.com)
3. If NO port works:
   • Server IP is likely blocked by TSPU
   • Solution: deploy Layer 1 relay on a Russian VPS (Timeweb/VDSina/Selectel)
   • Run: python ssh_exec.py deploy deploy-relay-sweden.sh (prepare main VPS)
   • Then rent a RU VPS and run: bash deploy-relay.sh --sweden-ip ... --sweden-uuid ... --sweden-pubkey ... --sweden-sid ...
   • NB: Yandex Cloud does NOT bypass white lists (AS Yandex.Cloud LLC != AS YANDEX LLC); use generic RU provider
   • See CLAUDE.md "Layer 1" section for full instructions
4. Client-specific issues:
   • v2rayN: ensure TUN mode is ON (toggle at bottom of window)
   • Shadowrocket: ensure "Global Routing" is set to "Proxy"
   • v2rayNG: ensure VPN permission is granted

Branch E: Connects Then Disconnects

1. Check logs: python ssh_exec.py logs -n 50
2. Look for repeated connection/disconnection patterns
3. Common cause: TSPU actively probing the connection
   • Try different port (8443, 2053)
   • Enable TLS fragmentation in client (100-400 bytes)

---

Step 4: Internet works through VPN?

Ask user: "Open 2ip.ru in your browser. What country does it show?"

Result	Action
Shows VPS country (Sweden/Netherlands/etc)	VPN works correctly. Go to Step 5 for optimization
Shows Russia	Go to Branch F
Page doesn't load at all	Go to Branch G

Branch F: 2ip.ru Shows Russia (VPN not routing traffic)

1. TUN mode check (critical!):
   • v2rayN: "Enable Tun" toggle must be ON (bottom of window). Without TUN, only apps configured for proxy work, browser goes direct
   • Hiddify: DO NOT use Hiddify — switch to v2rayN (Hiddify has known QUIC/UDP leaks, see docs/05-security.md)
2. Split routing check:
   • 2ip.ru IS a Russian site, so with split routing enabled it SHOULD show Russia
   • Test with a non-Russian site instead: whatismyipaddress.com or ifconfig.me
   • If non-Russian sites show VPS IP: split routing works correctly
3. Core type (v2rayN only):
   • Settings -> Core Type -> select "sing-box" (not Xray)
   • Xray core has known issues with QUIC through SOCKS5

Branch G: No Internet At All

1. DNS issue?
   • Try accessing a site by IP directly in browser
   • If works by IP but not by domain: DNS resolution broken
   • Fix: set DNS in client to 1.1.1.1 or 8.8.8.8
2. Routing issue?
   • Disable split routing temporarily (use "Global" mode)
   • If Global mode works: split routing config has errors
3. Server-side DNS:
   • Run: python ssh_exec.py exec "nslookup google.com"
   • If fails: python ssh_exec.py exec "systemctl restart systemd-resolved"

---

Step 5: Performance Issues

Symptom	Diagnostic	Fix
Slow overall	python ssh_exec.py exec "sysctl net.ipv4.tcp_congestion_control"	Should be "bbr". If not: python ssh_exec.py deploy quick-rebuild.sh will enable it
Slow on LTE	Mobile operator throttling	Enable TLS fragmentation (100-400 bytes) in client settings
YouTube buffers	Check core type in v2rayN	Switch to sing-box core. QUIC/UDP may be broken with Xray core
Slow on Wi-Fi, fast on LTE	Unusual, likely ISP issue	Try Cloudflare DNS (1.1.1.1) in router settings

---

Step 6: Works on Wi-Fi, Not on LTE

This is a specific and common problem caused by mobile operators using "white lists" (only allowing traffic to known Russian IPs).

Solution: Deploy Layer 1 (Relay on Russian VPS)

IP ranges of Russian VPS providers (Timeweb, VDSina, Selectel) may be in the white list of mobile operators — but this is NOT guaranteed. You must verify after deploy.

NB: Yandex Cloud was previously recommended here; removed 2026-04-17 after Habr 1021160 comments (@paxlo/@aax/@Varpun) proved AS Yandex.Cloud LLC (user VMs) != AS YANDEX LLC (Yandex services) — TSPU filters them separately, YC VMs get blocked under active white lists.

1. Prepare main VPS: python ssh_exec.py deploy deploy-relay-sweden.sh
2. Fill relay credentials in .env (SWEDEN_RELAY_UUID, SWEDEN_RELAY_PUBKEY, SWEDEN_RELAY_SID)
3. Rent a Russian VPS (Timeweb Cloud ~80 RUB/mo, VDSina ~100 RUB/mo), fill RELAY_HOST in .env
4. Deploy relay: bash deploy-relay.sh --sweden-ip $SWEDEN_VPS_IP --sweden-uuid $SWEDEN_RELAY_UUID --sweden-pubkey $SWEDEN_RELAY_PUBKEY --sweden-sid $SWEDEN_RELAY_SID
5. Import the relay VLESS URI into client
6. Test on LTE — if blocked, try a different Russian provider

See CLAUDE.md "Layer 1" section for details.

---

Relay VPS Troubleshooting

If user has Layer 1 (relay) deployed and it stops working:

1. python ssh_exec.py -t relay status — check relay xray
2. python ssh_exec.py -t relay logs — check relay logs
3. python ssh_exec.py -t relay restart — restart relay
4. bash monitor-relay.sh — health check both VPSes
5. Verify main VPS accepts relay connections: python ssh_exec.py exec "ss -tnp | grep 10443"

Communication Rules

• Communicate in Russian
• Run diagnostic commands BEFORE suggesting fixes
• Show the user what each command found (summarize, don't dump raw output)
• If a fix doesn't work, go back to diagnostics, don't keep guessing
• For complex issues, reference docs/08-operations.md for additional guidance