Troubleshooting Guide

Detailed solutions for every common issue. Find your problem, follow the fix, get back online. If nothing here works, contact support.

Cannot Connect Slow Speeds ISP-Specific Issues Sensitive Period Issues AI Tool Issues General Issues

Cannot Connect

App shows "Connection Failed" or "Timeout"

Possible causes:
  • App not running as administrator
  • System clock out of sync
  • ISP blocking port 443 to the server IP
  • Antivirus or firewall blocking sing-box
Solutions:
  1. Right-click KookVPN and select "Run as administrator". TUN mode requires admin privileges.
  2. Sync your system clock: Settings > Time & Language > ensure "Set time automatically" is ON. Reality protocol authentication is time-sensitive -- even a 2-minute clock drift can cause failures.
  3. Try connecting from a different network (mobile hotspot) to rule out ISP-specific blocking.
  4. Add sing-box.exe and KookVPN to your antivirus/firewall whitelist. Windows Defender, Kaspersky, and Norton are known to block TUN drivers.

App shows "Failed to create TUN adapter"

Possible causes:
  • Missing wintun.dll
  • Conflicting virtual adapter
  • Insufficient permissions
Solutions:
  1. Verify wintun.dll exists in the KookVPN installation directory (same folder as sing-box.exe).
  2. Disable other VPN software, Hyper-V virtual switches, or network virtualization tools that may conflict with the TUN adapter.
  3. Run the app as administrator. If still failing, try reinstalling KookVPN to ensure wintun.dll is properly placed.
  4. Open Device Manager and check for any error indicators on network adapters. Remove any stale "Wintun" adapters.

Connects briefly then disconnects immediately

Possible causes:
  • Incorrect credentials
  • Server-side issue
  • Reality key mismatch
Solutions:
  1. Verify your VLESS UUID, Reality public key, and short ID match what was provided in your welcome email.
  2. Check that the server address (IP or domain) is correct.
  3. Contact support -- this may indicate a server-side configuration change.

Slow Speeds

Speeds significantly lower than expected

Possible causes:
  • ISP throttling international traffic
  • Peak hour congestion
  • China Mobile routing issues
  • BBR not active
Solutions:
  1. First, test your base speed WITHOUT VPN. If your base speed is low (under 30 Mbps), the issue is your ISP, not KookVPN.
  2. Avoid peak hours (7-11 PM CST / UTC+8). All three Chinese ISPs throttle international bandwidth during evening hours.
  3. If you are on China Mobile: this ISP has the worst international routing. Consider switching to China Telecom or China Unicom for significantly better VPN performance.
  4. China Telecom users: Check if you are on the 163 backbone or CN2 (premium). CN2 provides much better international routing. Contact your ISP to inquire about upgrading.
  5. Ensure BBR is enabled on the server (it is by default on KookVPN). BBR optimizes TCP throughput on high-latency, lossy connections typical of China-to-international paths.

YouTube/Netflix buffers constantly

Possible causes:
  • Insufficient bandwidth
  • DNS resolution delays
  • Server routing suboptimal for streaming CDN
Solutions:
  1. YouTube 4K requires ~25 Mbps sustained. If your base speed with VPN is below this, try reducing to 1080p.
  2. Ensure DNS-over-TLS is active (default in KookVPN). Slow or failed DNS lookups can cause perceived buffering.
  3. Some streaming CDNs route differently depending on the source IP. If specific services are slow while others are fast, contact support -- we may need to adjust routing.

Speed fluctuates wildly during the day

Possible causes:
  • ISP congestion patterns
  • GFW variable enforcement
  • Shared backbone saturation
Solutions:
  1. This is normal behavior in China. The 163 backbone (China Telecom standard) and CMNet (China Mobile) experience significant congestion during peak hours.
  2. Best speed windows: 6-9 AM and 1-5 PM CST (when US/EU is sleeping and Chinese evening traffic has not started).
  3. For business-critical tasks, schedule bandwidth-heavy operations (large file transfers, video calls) during off-peak hours.

ISP-Specific Issues

China Telecom: Connection works but speeds are poor

Possible causes:
  • 163 backbone vs CN2 routing
  • Inter-carrier bridging delays
Solutions:
  1. Check your Telecom plan: standard plans use the 163 backbone, while premium plans use CN2 (China Next Carrying Network). CN2 has dramatically better international routing.
  2. Typical 163 backbone performance: 40-60 Mbps to Singapore with 60-80ms latency. CN2: 80-120 Mbps with 30-40ms latency.
  3. Consider upgrading to a CN2 plan if available in your area. The cost difference is modest compared to the performance improvement.

China Unicom: Good speeds but occasional drops

Possible causes:
  • 169 backbone routing changes
  • Peering point saturation
Solutions:
  1. China Unicom generally offers the best balance of speed and stability for VPN use.
  2. If experiencing drops, they may coincide with routing table changes at peering points. Wait 10-15 minutes and try reconnecting.
  3. Unicom residential connections tend to perform better than business connections for international traffic (counterintuitively).

China Mobile: Everything is terrible

Possible causes:
  • CMNet has the worst international routing
  • Aggressive UDP throttling
  • Heavy restrictions on mobile data
Solutions:
  1. China Mobile is genuinely the worst ISP for VPN use. Their CMNet backbone has the least international peering capacity and the most aggressive throttling.
  2. If possible, switch to China Telecom or China Unicom. This single change can improve VPN speeds by 2-3x.
  3. If stuck on China Mobile: use WiFi instead of mobile data (mobile data has additional restrictions), avoid peak hours entirely, and lower expectations for streaming quality.
  4. VLESS+Reality over TCP (which KookVPN uses) works better on China Mobile than UDP-based protocols (Hysteria2, WireGuard) because China Mobile heavily throttles UDP.

Sensitive Period Issues

VPN works fine normally but struggles during political events

Possible causes:
  • GFW enforcement escalation
  • Increased DPI sensitivity
  • Bandwidth throttling on international links
Solutions:
  1. During sensitive periods (NPC in March, National Day in October, June 4th anniversary), the GFW increases enforcement significantly.
  2. VLESS+Reality should continue working during these periods because it is indistinguishable from normal HTTPS traffic. If you experience issues, it is likely ISP-level bandwidth throttling rather than protocol detection.
  3. During extreme throttling: reduce bandwidth-heavy activities, use text-based communication over video calls, and schedule large downloads for 2-6 AM CST when enforcement is typically lightest.
  4. Known sensitive periods: National People's Congress (March), Tiananmen Anniversary (June 4), National Day / Golden Week (October 1-7), Communist Party Congress (every 5 years, next 2027).
  5. If KookVPN stops working during a sensitive period, contact support immediately. This has not happened to date, but if it did, we would investigate and rotate the server IP if needed.

AI Tool Issues

Claude Code / Codex CLI returns "Access denied" or "Region not supported"

Possible causes:
  • VPN not capturing CLI traffic
  • DNS leak exposing location
  • IP blacklisted by AI provider
Solutions:
  1. Verify KookVPN is connected and TUN mode is active. The system tray icon should show a connected state.
  2. Test: Open a terminal and run "curl ifconfig.me" -- the IP should show your Singapore VPN IP, not your China ISP IP.
  3. If the IP shows your China ISP: KookVPN may not have TUN mode active. Restart the app as administrator.
  4. Run a DNS leak test at dnsleaktest.com. If Chinese DNS servers appear, your DNS is leaking. Restart KookVPN to reinitialize DNS-over-TLS.
  5. If your VPN IP is clean but you still get access denied: the AI provider may have flagged your account previously from a leaked IP. Contact the AI provider's support to discuss your account status.

VPN disconnects during long API sessions

Possible causes:
  • Auto-sleep interrupting connection
  • ISP connection reset
  • Inactivity timeout
Solutions:
  1. Ensure your computer is set to never sleep during VPN usage: Settings > Power > set "When plugged in, turn off screen after: Never" and "When plugged in, put device to sleep after: Never".
  2. The kill switch ensures no traffic leaks during disconnection, and auto-reconnect will restore the connection. Your API call may time out, but your IP will not be exposed.
  3. For extended sessions (overnight training runs, long builds), monitor the KookVPN connection status periodically.
  4. If disconnects happen frequently: contact support with your ISP name, approximate time of disconnections, and any error messages.

General Issues

App does not start or crashes on launch

Possible causes:
  • Missing runtime dependencies
  • Corrupted installation
  • Conflicting software
Solutions:
  1. Ensure .NET Desktop Runtime 6.0+ is installed (the installer should handle this automatically).
  2. Try reinstalling KookVPN from a fresh download.
  3. Disable other VPN software (Astrill, ExpressVPN, etc.) before launching KookVPN. Running two VPN clients simultaneously causes conflicts.
  4. Check Windows Event Viewer (eventvwr.msc) for crash logs and send them to support.

Chinese apps (WeChat, Alipay) stop working when VPN is on

Possible causes:
  • Split routing not configured properly
  • All traffic being routed through VPN
Solutions:
  1. This should not happen with KookVPN's default split routing configuration, which sends Chinese app traffic directly.
  2. If it does occur: disconnect and reconnect. The split routing rules may not have loaded correctly.
  3. Contact support -- we may need to add specific domains to the direct-route list for your use case.

Still Stuck?

Include your operating system, ISP name, time of day, and any error messages when contacting support. This helps us diagnose faster.

Contact Support Browse FAQ

Ready to finally have a VPN that works?

Join hundreds of expats who stopped fighting the Great Firewall and started winning.

Get KookVPN Now See How It Works