Troubleshooting Manual · Organized by Symptom

V2Ray Troubleshooting Guide

Organized by symptom, this guide helps you diagnose V2Ray client issues: no internet, node timeouts, subscription failures, slow speeds, DNS errors, system proxy not working, client crashes, and mobile-specific problems. Each chapter provides a complete troubleshooting workflow, explains the underlying principles, and offers fixes. The quick start guide covers "how to use" V2Ray; this manual covers "what to do when something breaks" — read them together.

  • Last updated: 2026-09-10
  • Applies to: v2rayN / v2rayNG / v2flyNG
  • Platforms: Windows · macOS · Android · Linux
  • Reading time: about 25 minutes
01

General Principles: Logs, Versions, and Minimal Verification

First pin down the symptom, then identify which layer is at fault, and only then change configuration. This chapter is the common starting point for every other chapter.

The first step in troubleshooting is not to change settings but to pin down the symptom. The same 'can't connect' could mean the system proxy isn't taking over, the node is dead, DNS resolution failed, or routing rules are blocking traffic - each requires a completely different fix. Every chapter in this manual follows the order 'confirm the symptom → locate the layer → change the config', so you don't end up toggling the client on and off without knowing the cause. The Quick Start Guide covers how to use it; this manual covers what to do when it breaks. Read them together.

Before you start, confirm three things: the client version, the core version, and the system time. All three are visible in the logs and configuration screens — write them down before you begin, and you'll save yourself a lot of trial and error.

Logs: First-Hand Evidence for Connection Issues

Logs are the first-hand evidence for diagnosing problems. In v2rayN, the log entry is under the "View Log" menu, which records connection and routing events by default. When troubleshooting handshake failures or TLS errors, set the log level to "Debug" and reproduce the issue once more to capture the full connection sequence. In v2rayNG, logs are under "Settings → Logging", also with per-level output. The following table maps log keywords to troubleshooting directions:

Log KeywordTypical MeaningTroubleshooting Direction
connection refusedNo service listening on the target portNode timeout: port and firewall
i/o timeoutNo response on the network pathNode timeout: route and server
x509 / certificateTLS certificate verification failedDNS issues: time and SNI
unexpected EOFConnection closed by peerNode timeout: protocol mismatch
context canceledRequest terminated locallySystem proxy: routing and timeout

Version and Core: Two Independent Variables

The client version and the core version are two independent variables. In v2rayN, you can view and switch the core (Xray-core or V2Fly-core) under "Settings → Parameter Settings → Core"; v2rayNG ships with the Xray core built in, and v2flyNG uses the v2fly core. To check versions: v2rayN shows the client version on the main screen, and the core version at the top of "Settings → Parameter Settings → Core"; v2rayNG shows version and core info on the "About" page. If problems appear after upgrading the client, first check whether the core version changed at the same time. The two don't need to match exactly, but if they differ too much, some config fields may be incompatible — usually showing up as an immediate error on startup or certain nodes failing to connect.

System Time: A Frequent Source of TLS Errors

If the device time is off by more than a few minutes from real time, certificate verification will fail outright. The symptom: the node list looks fine and latency tests pass, but connections fail instantly with certificate-related errors in the log. Put "calibrate the system time" at the very top of your troubleshooting order — it's the cheapest check with the highest hit rate. Windows, macOS, and Android all support automatic network time sync; enable it, restart the client, and try again.

Minimal Verification: Cross-Check with Two Test Methods

When verifying connectivity, use two methods at once: open the target site in a browser incognito window to rule out extension and cache interference, and run a curl command in the terminal — command-line results are closer to the real link state than the browser.

# Access the target site through the local SOCKS proxy
curl -x socks5h://127.0.0.1:10808 -I https://www.google.com

# Access the target site through the local HTTP proxy
curl -x http://127.0.0.1:10809 -I https://www.google.com

# View the active proxy environment variables (Linux / macOS)
env | grep -i proxy

Use the ports the client is actually listening on for both commands. v2rayN's default SOCKS port is 10808 and HTTP port is 10809; you can view and change them under "Settings → Parameter Settings → Local Listening".

When recording the symptom, note these three things: client and core versions, node protocol and transport, and the exact error message. Jump to the matching chapter with this info and you'll usually hit the root cause directly.

02

No Internet: A Step-by-Step Check from System Proxy to Routing Rules

The main line of investigation for "connected but no internet": is the proxy taking traffic, is the link usable, and is traffic being blocked by rules.

"Connected but no internet" is the most common failure mode. It means the client has established a proxy link, but traffic isn't entering that link correctly, or it's being blocked by a rule somewhere along the way. Work through the following steps in order — each one has a clear pass criterion.

Step 1: Check the System Proxy Status

v2rayN's tray menu has a "System Proxy" submenu with three states: "Auto Configure System Proxy", "Do Not Change System Proxy", and "Clear System Proxy". After choosing "Auto Configure System Proxy", Windows and macOS write a system-level proxy pointing to the local port. If this is set to "Clear System Proxy", browser traffic won't go through the client. To check: open the system network settings and verify the proxy server address is 127.0.0.1 plus the corresponding port. On Android, v2rayNG doesn't use the system proxy — it takes over traffic through a VPN tunnel, so the corresponding check is in the system's "VPN settings".

Step 2: Direct Connection Control Test

Turn off the client proxy and visit a site inside mainland China directly. If direct access also fails, the problem is in your local network itself, not the proxy — fix your Wi-Fi or broadband first. If direct access works but everything fails with the proxy on, continue to the next step. This step quickly distinguishes "local network failure" from "proxy link failure" — don't skip it.

Step 3: Verify Node Connectivity

In the v2rayN main window, select the current node and click "Test Real Connection Delay". Note the difference between two results: a TCP-only latency reading only means the port is reachable, not that the proxy handshake succeeded; "Real Connection Delay" actually runs the protocol handshake, so it's more trustworthy. If the real connection test fails, try another node: if all nodes fail, the problem is in the local link or client config; if only some nodes fail, the problem is on those node servers — handle it per Chapter 3.

Step 4: Check the Routing Mode

The routing mode determines which traffic goes through the proxy. v2rayN commonly uses three: "Bypass Mainland" — mainland China addresses connect directly, everything else goes through the proxy, good for daily use; "Global" — all traffic goes through the proxy; "Direct" — nothing goes through the proxy. If you're on "Bypass Mainland" and the target site is classified as mainland China, traffic will connect directly, which looks like "proxy is on but the site won't open". Temporarily switch the routing mode to "Global" and try again — if it works, the issue is in the split-routing rules; switch back to "Bypass Mainland" and adjust DNS and rules per Chapter 6.

Step 5: DNS and Browser Cache

If routing mode is fine but some domains fail to resolve, check DNS. In v2rayN's "DNS Settings", if remote resolution is enabled, local DNS pollution is bypassed; if resolution requests go through the local DNS, pollution can return wrong IPs — the symptom is domains won't open but direct IP access works. On the browser side, retest in an incognito window first to rule out cache and extensions.

  • System proxy is set to "Auto Configure System Proxy"
  • Direct connection control: local network works with the proxy off
  • Node test: "Real Connection Delay" test passes
  • Routing mode matches the target site's region
  • Browser side: incognito window works but normal window doesn't — clear cache and extensions
  • Fallback: still failing after switching nodes — check local firewall and antivirus

For more detailed platform-specific steps, see the tech note "v2rayNG Connected but No Internet: A Step-by-Step Checklist from System Proxy to Routing Rules".

03

Node Timeout: Connectivity Checks and Server-Side Factors

Look at the timeout pattern in the logs first, then decide which direction to investigate: port, protocol, route, or certificate.

The difference between node timeouts and "no internet" is this: a timeout means the proxy link failed to establish; "no internet" means the link was established but traffic isn't going the right way. The key to troubleshooting timeouts is figuring out which segment is failing — local to server, server to target site, or the protocol handshake itself.

Distinguishing Three Timeout Patterns

A connection timeout (common log entries: dial tcp or connect: connection refused) means the local-to-server port is unreachable — possible causes include a blocked port, a dead server, or local firewall interception. A handshake timeout means TCP is established but the protocol layer isn't responding — common causes are a wrong protocol type, mismatched TLS settings, or an overloaded server. A read timeout means the handshake succeeded but the data stream stalled — usually related to line quality or restricted server egress. The three patterns point to different troubleshooting directions:

Timeout PatternLog SignaturePrimary Direction
Connection timeoutdial tcp / connection refusedPort, firewall, server liveness
Handshake timeouttimeout waiting for ... handshakeProtocol and transport, TLS settings
Read timeoutread tcp ... i/o timeoutLine quality, server egress

Server-Side Factors

A closed port or a protocol configuration mismatch is the most common cause. Check that the port in the node info matches what the server is actually listening on, and that the protocol (VMess/VLESS/Trojan), transport (ws/grpc/tcp), and TLS toggle strictly match the server config. For example, if the server is VLESS + Reality but the client is set to VLESS + TLS, the handshake is guaranteed to fail. These errors usually show up in the log as a handshake timeout or EOF. Also, if the server has a firewall or cloud security group that only allows port 443, but the node is configured with a different port, you'll get connection timeouts as well.

Local Factors

Local firewalls, antivirus software, and proxy tool conflicts can block outbound connections. On Windows, temporarily disable the firewall or add an allow rule for the client; on macOS, check "System Settings → Network → Firewall" for inbound blocks; on Linux, check the status of ufw or firewalld. If the system has IPv6 enabled but the node doesn't support it, IPv6-first connection attempts can cause timeouts — disable "Prefer IPv6" in the client or temporarily disable system IPv6 to verify. Corporate and campus networks often restrict non-standard ports, so in those environments prefer nodes on port 443.

Diagnostic Commands and Logs

Reproduce with the log level set to "Debug" and focus on the last two records before the connection fails. From the command line, use nc or curl for targeted tests:

# Test whether the TCP port is reachable (5-second timeout)
nc -vz -w 5 <server-address> <port>

# Access the target site through the local SOCKS proxy
curl -x socks5h://127.0.0.1:10808 -v https://www.google.com

If nc returns succeeded, the port is reachable and the problem is at the protocol layer; if it returns timeout or connection refused, the problem is at the port or network layer. When the log shows certificate-related messages, first calibrate the system time, then verify that the node's SNI matches the server domain — these two are the most common causes of TLS timeouts. For a full analysis of TLS certificate errors, see the tech note "V2Ray TLS Handshake Failures and Certificate Errors: System Time, SNI, and allowInsecure Explained".

If timeouts persist after switching nodes, and multiple nodes and protocols all fail, suspect local network restrictions on outbound connections. Try a node on port 443, or switch to a UDP-based transport to verify.

04

Subscription Failures: URL, Format, and Update Timing

Subscription failures come down to three things: the subscription URL itself, whether the subscription server is reachable, and the format of the returned content.

Subscription failures usually come down to three things: the subscription URL itself, whether the subscription server is reachable, and the format of the returned content. Both v2rayN and v2rayNG support batch-importing nodes from subscriptions. When a subscription fails, work through the following checks in order — most issues are resolved within the first three steps.

Check the Subscription URL

A complete subscription address should start with https:// and have no trailing spaces or line breaks. When copying subscription links, chat apps often append spaces or truncate line breaks, which is hard to spot after pasting. In v2rayN, open "Subscription Group → Subscription Group Settings", paste the URL into the input field, and verify it character by character; do the same in v2rayNG under "Subscription Settings". If the URL contains & parameters, make sure the copy didn't drop the parameter segment. Some providers offer multiple subscription addresses (e.g., a base64 version and a Clash version) — make sure you're using the format the client supports.

Check Network Reachability

The subscription server must be directly reachable from your local network — unlike the sites you proxy. If the local network can't resolve the subscription domain, subscription updates will fail. To tell: open the subscription URL directly in a browser — if you can download a block of text, the network is reachable; if not, fix the subscription domain's resolution first, temporarily add the subscription domain to the proxy rules, or switch to a mirror address that works. v2rayN's "Update Subscription (No Proxy)" fetches the subscription through the current proxy, which suits cases where the subscription domain itself isn't directly reachable.

Check the Content Format

The subscription response may be a base64-encoded list of v2ray links, or in formats like Clash or sing-box. v2rayN recognizes common formats; v2rayNG mainly recognizes the standard v2ray format and base64. If the response is an HTML error page or an empty file, the subscription endpoint itself is broken — not the client. To verify manually: paste the downloaded text into an online decoder, or just look at the beginning — links starting with vmess://, vless://, or trojan:// are standard links, while a long base64 string at the start means an encoded list.

Update Timing and Caching

Subscription update frequency is controlled by the group settings. Newly added nodes won't appear immediately — you need to manually click "Update Subscription". If you just updated and click again right away, some subscription servers have rate limits and will return 429 or empty content. In v2rayN, the "Subscription Group" right-click menu offers "Update Subscription" and "Update Subscription (No Proxy)" — choose based on your network situation.

Manual Import as a Fallback

When the subscription server is unavailable, you can import nodes manually. v2rayN supports importing from the clipboard: copy a full link starting with vmess:// or vless://, then use "Clipboard Import" in the tray menu. v2rayNG also supports "Import from Clipboard". Importing a single node doesn't depend on the subscription endpoint, making it an effective emergency troubleshooting method — test the latency before using it.

SymptomCommon CauseFix
Subscription update returns emptyTrailing space or line break in the URLRe-copy and verify character by character
Returns 404 / 403Subscription link is deadContact the provider to regenerate the subscription address
Returns an HTML pageSubscription address is reverse-proxied to a login pageCheck the subscription domain's availability
Import succeeds but all nodes time outSubscription contains expired nodesUpdate the subscription and test again
Format not supported errorResponse is in Clash or sing-box formatUse a client or converter that supports that format
05

Slow Speed: Three-Layer Troubleshooting — Node, Route, and Local Settings

First determine which layer the bottleneck is in, then adjust that layer — avoid blindly switching nodes.

Slow speed is the hardest issue to pin down at once, because the factors span three layers: server, route, and local. This guide uses layered troubleshooting: first determine which layer the bottleneck is in, then adjust that layer — avoid blindly switching nodes. For a complete layered approach to speed issues, see the tech note "v2rayN Slow Speed: A Three-Layer Troubleshooting Method — Node, Route, and Local Settings".

Run a Reliable Speed Test First

Don't judge speed by latency numbers. Latency only reflects handshake round-trip time and has no linear relationship with download throughput. To test: first run a "Real Connection Delay" test on the node in v2rayN to confirm the link works, then actually download a file from the command line:

curl -o /dev/null -w "%{speed_download}\n" \
  -x socks5h://127.0.0.1:10808 \
  https://speed.cloudflare.com/__down?bytes=10000000

Run the test three times and take the median to rule out transient fluctuations. If speeds differ dramatically between morning rush hour and late night, the bottleneck is at the server and route layer — no local setting can change that ceiling.

Node and Route Layer

Node load, bandwidth caps, and route quality determine the speed ceiling. Among multiple nodes from the same provider, pick the one with lower load; between different providers, route differences can mean several-fold gaps. Transport also matters: on weak networks, grpc and reality handle packet loss better than raw tcp; in environments where ISPs throttle UDP, UDP-based transports can be slower than TCP. Record the node protocol and transport, and keep the same parameters when switching nodes so comparisons are meaningful.

Local Settings Layer

Local client settings affect speed in three places. First, the log level — "Debug" significantly increases overhead; switch back to "Info" or "Warning" after troubleshooting. Second, the number of routing rules — more rules mean more time spent on split-routing decisions per connection; trim unnecessary rules. Third, the mux (multiplexing) toggle — on high packet-loss routes, mux can amplify retransmission overhead, and turning it off is sometimes faster. In v2rayN, these are under "Settings → Parameter Settings → Routing" and "Settings → Parameter Settings → Core".

System Level

DNS resolution time shows up on the first visit to each new domain. When the local DNS is polluted, resolution times out and retries, which looks like "the page stalls for a few seconds then loads" — enabling the client's remote DNS or FakeDNS shortens that wait. MTU mismatch causes large packets to be fragmented and dropped, with symptoms like pages opening but large downloads crawling — try lowering MTU from 1500 to around 1400 in the system network settings to verify. Antivirus real-time scanning also slows downloads; add the client directory to exclusions.

Check ItemLow-Risk AdjustmentExpected Benefit
Log level"Debug" → "Info"Lower CPU overhead, more stable connections
Routing rulesTrim unnecessary rulesLess time spent on split-routing decisions per connection
muxTurn off and comparePossible speedup on high packet-loss routes
DNSEnable remote resolution or FakeDNSLess waiting on DNS resolution
MTU1500 → 1400 to verifyFixes download stalls caused by large-packet fragmentation
06

DNS Resolution Issues: Split-Routing Failures and Pollution

Three symptom types: resolution failures, domains that should go through the proxy connecting directly, and resolution results pointing to wrong IPs.

DNS problems usually show up in three forms: some domains fail to resolve, domains that should go through the proxy connect directly, and resolution results point to wrong IPs. DNS configuration is an advanced capability of the Xray core — once you understand the config structure, most issues can be solved within the dns section.

Identifying DNS Symptoms

Domains that won't open but work via direct IP access are a classic sign of DNS pollution. Sites that should go through the proxy but connect directly usually mean the resolution result hit the "Bypass Mainland" IP-range check. Another common case: the node list and connections are fine, but certain sites have login issues or captchas won't load — often related to DNS returning polluted intermediate results. Note that DNS-related errors are sometimes mistaken for node problems — when the log shows resolution failed or no such host, check DNS before checking nodes.

Xray DNS Configuration Structure

Xray's DNS configuration lives in the dns section, with the servers list and queryStrategy at its core. You can configure local DNS (e.g., 223.5.5.5) and remote DNS (e.g., 1.1.1.1 or a DoH address) at the same time, and use domain rules to decide which domains go to which server:

{
  "dns": {
    "servers": [
      {
        "address": "1.1.1.1",
        "domains": ["geosite:geolocation-!cn"]
      },
      {
        "address": "223.5.5.5",
        "domains": ["geosite:cn"],
        "expectIPs": ["geoip:cn"]
      }
    ],
    "queryStrategy": "UseIP"
  }
}

The structure of this example: non-mainland-China domains go to the remote DNS, mainland China domains go to the local DNS, and the returned IP is checked against mainland China IP ranges. Replace the addresses in the example with your own DNS servers in practice. Note that the order of servers carries priority — when domain rules overlap, the first match wins.

When to Enable FakeDNS

FakeDNS replaces real resolution with virtual IPs from a reserved range, so domain rules still work in transparent proxy and TUN modes while saving one DNS round trip. Where to enable it in v2rayN: "Settings → Parameter Settings → Core → Enable FakeDNS". Good for: TUN mode, domain-level split routing, and polluted local DNS. Not good for: system proxy only, strong need for direct IP connections, and apps sensitive to virtual IPs. If login issues or certificate errors appear after enabling it, turn FakeDNS off first and compare. FakeDNS and remote DNS can be enabled together — the former handles domain rule matching, the latter handles trustworthy resolution results. For the principles and limits, see the tech note "What Is FakeDNS: Xray Core Virtual IP Resolution Principles and When to Enable It".

Browser DoH vs. System DNS Conflicts

The browser's built-in "Secure DNS" (DoH) bypasses both system and client DNS settings, querying the DoH server configured in the browser directly, which breaks split routing. To check: temporarily disable Secure DNS in the browser and see if domain resolution returns to normal. If you need domain-level split routing, it's recommended to turn off browser DoH and hand all resolution to the client. The same applies to Android's system-level "Private DNS" — set it to "Automatic" or turn it off.

For a full guide on DNS split routing and anti-pollution configuration, see the tech note "V2Ray DNS Configuration Guide: Split Resolution for Domestic and International Domains with Anti-Pollution".

07

System Proxy Not Working: Takeover Scope and Port Conflicts

The key checks are the proxy port and takeover scope: whether the port is occupied, whether the system proxy points to the right address, and whether apps actually read the system settings.

The difference between "the client shows connected but the browser isn't using the proxy" and "no internet" is this: the former means the proxy isn't being used by the system or apps; the latter means the proxy link itself is broken. This type of problem comes down to the proxy port and takeover scope.

Confirm the Local Listening Ports

v2rayN listens on two local ports by default: SOCKS 10808 and HTTP 10809. The system proxy must point to one of these two ports. If the port is occupied, the client may automatically switch ports, leaving the system proxy pointing at a dead port. To check: view the actual ports under "Settings → Parameter Settings → Local Listening" and compare with the address in the system proxy settings. From the command line, confirm the listening state with:

# Windows: check whether port 10808 is listening
netstat -ano | findstr 10808

# Linux / macOS: check whether port 10808 is listening
lsof -i :10808

If the port is occupied by another program, kill the occupying process or change the local port in the client settings. Note that after changing the port, you must update the system proxy address to match.

Auto-Configuration Mechanisms and Platform Differences

"Auto Configure System Proxy" works differently on each platform: Windows writes to the system proxy registry, macOS modifies the network service configuration, and Linux desktop environments usually rely on environment variables or desktop settings. Many Linux distributions don't set a system proxy automatically — you need to export the environment variables manually:

export http_proxy=http://127.0.0.1:10809
export https_proxy=http://127.0.0.1:10809
export socks5_proxy=socks5h://127.0.0.1:10808

These variables only apply to the current terminal. GUI apps need to read them from desktop settings or startup scripts. On macOS, after switching Wi-Fi networks, old proxy settings may linger, which looks like "system proxy shows as set but isn't actually working" — toggling "Auto Configure System Proxy" off and on refreshes it.

PlatformAuto-Proxy Entry PointCommon Failure Cause
WindowsSettings → Network → ProxyThird-party proxy software repeatedly writes to the registry
macOSSystem Settings → Network → ProxyNot reapplied after network service switch
LinuxEnvironment variables / desktop proxy settingsDesktop environment doesn't read environment variables

Browser Extension Takeover Conflicts

Proxy extensions like SwitchyOmega take over traffic at the browser level, bypassing the system proxy. If the port configured in the extension doesn't match the client's actual port, the browser will fail to connect directly. To check: temporarily disable the proxy extension, or change the port in the extension to the client's actual listening port. The browser's own "Secure DNS" also bypasses proxy settings — check that too.

Common Reasons Apps Don't Use the Proxy

Some apps don't read the system proxy and need separate configuration. Windows UWP apps are affected by network isolation — try turning off related "network isolation" settings; most native macOS apps follow the system proxy, but command-line tools need environment variables. v2rayN offers "TUN Mode", which takes over all traffic through a virtual network adapter and works best for apps that ignore the system proxy. With TUN enabled, the system proxy setting is no longer required, but it needs administrator privileges and can conflict with some VPN software.

  1. Confirm the client's actual listening port — check under "Local Listening" and compare with the system proxy address.
  2. Verify the system proxy target — check the proxy server address in Windows and macOS system network settings.
  3. Disable browser proxy extensions and retest — rule out extension-level takeover.
  4. Export environment variables in the terminal and retest — confirm command-line tools can use the proxy.
  5. If still not working, enable TUN mode — take over all traffic through a virtual network adapter.
08

Client Crashes: Log-Based Diagnosis and Config Reset

Follow the order "back up first, then reset, then restore" to avoid repeatedly restarting with a corrupted configuration.

Client crashes fall into three categories: crashes on startup, crashes during connection, and crashes while updating subscriptions. Most crashes are caused by corrupted configs, missing core files, or port conflicts. The workflow below gets you reset quickly. Follow the order "back up first, then reset, then restore" to avoid repeatedly restarting with a corrupted configuration.

Crashes on Startup

For crashes on startup, suspect a corrupted configuration first. v2rayN stores its config in guiConfig-related files under the user directory; if they're corrupted, the client fails to read them during startup. To fix: exit the client, rename the entire config directory as a backup (e.g., add a .bak suffix), then start again — the client will rebuild with default config. Keep the backup directory outside the client data directory to avoid it being read again. If it still crashes after renaming, check whether security software is blocking the client process. After rebuilding, re-import the subscription to restore the node list.

Crashes During Connection

Crashes during connection are often caused by a core/config mismatch. After switching the core in v2rayN (Xray-core / V2Fly-core), some fields in the old config may not be recognized by the new core. To fix: switch back to the original core under "Settings → Parameter Settings → Core", or delete the nodes and re-import from the subscription. Also, running at "Debug" log level for a long time can produce huge log files that fill the disk and cause problems — switch back to "Info" after troubleshooting.

Missing Core Files and Antivirus Quarantine

When core files are missing, the client reports that it can't find the core on startup. The common cause is antivirus software quarantining the core executable as a threat. To fix: restore the file from the antivirus quarantine and add the client directory to the trust list. In v2rayN, you can re-download the core under "Settings → Parameter Settings → Core"; if the download fails, confirm the local network can reach the core download address, and download through the proxy if necessary. v2rayNG's core is bundled with the installer — if a missing-core prompt appears, reinstall first, and get the installer from the download center.

Port Conflicts

When a local port is occupied by another program, the client fails to listen, which shows up as exiting immediately after startup or the proxy not working. Use netstat or lsof to find the occupying process, kill it, or change the local port in the client settings. Port conflicts are also common when running multiple proxy clients at once — they use the same default port set.

v2rayNG Crash Handling

After a v2rayNG crash, you can clear the app data and re-import the subscription. On Android, if the crash happens in the background, check whether battery optimization is freezing the app — add it to the "Unrestricted" battery policy. v2flyNG is handled the same way; note that the two clients' configs are not compatible, so don't copy data directories between them. Clearing data also deletes subscriptions and settings, so copy the subscription address first.

  1. Back up the config directory — rename it entirely to preserve the failure state.
  2. Restore default config and start — confirm the client opens normally.
  3. Re-import the subscription — restore the node list.
  4. Check core integrity — confirm the core file hasn't been quarantined or deleted.
  5. Check port usage — confirm the local port isn't occupied by another program.

After a crash, verify with a "minimal config" first: keep only one node, turn off custom routing rules, confirm stable connections, then restore settings one by one.

09

Mobile-Specific: v2rayNG and v2flyNG Troubleshooting

Mobile troubleshooting differs in three areas: background keep-alive, system-level proxy takeover, and battery/network policies.

Mobile troubleshooting differs from desktop in three areas: background keep-alive, system-level proxy takeover, and battery/network policies. This section covers common issues with v2rayNG and v2flyNG; Android versions vary widely, so the steps below use general settings.

Connected but Apps Don't Use the Proxy

On Android, v2rayNG uses a VPN tunnel to take over traffic by default, so you need to allow the app to establish a VPN connection in the system's "VPN settings". If the connection icon looks normal but the target app still connects directly, check the routing mode: on the default "Bypass Mainland", domestic apps connect directly; if an app that needs the proxy is classified as domestic, it will fail to connect directly. Temporarily switch routing to "Global" to verify, or, when using "Per-App Proxy", confirm the target app is checked. Some devices impose extra power-saving restrictions on VPN — turn off the "power saving policy" restriction on VPN in "App info".

Disconnects from Background App Kill

Android freezes background apps to save power; when v2rayNG is frozen, the VPN tunnel drops. To fix: add v2rayNG to the "battery optimization whitelist" in system settings; some devices also require allowing auto-start in "auto-start management". Enabling v2rayNG's "Auto Reconnect on Connect" can mitigate brief disconnects, but the root cause is still background restrictions. ROMs from different manufacturers vary widely in background policy — when you hit disconnects, first check the "Battery" page for app-freeze notices.

Subscription Update Failures

Subscription update failures on mobile are often related to system time or certificates. If Android's automatic time sync is off, the time offset causes HTTPS certificate verification to fail and subscription requests are rejected. To fix: enable "Automatic date & time" and calibrate the time zone. Also, some subscription domains aren't directly reachable on mobile networks — enable "Update via Proxy" in v2rayNG's subscription settings, provided you have a working node. After switching between Wi-Fi and mobile data, subscription updates can also fail because the network state hasn't refreshed — toggle airplane mode on and off and try again.

Private DNS vs. Proxy Conflicts

Android's "Private DNS" feature bypasses app-level DNS settings and conflicts with the client's domain split routing. Symptom: the client shows connected but some domains resolve incorrectly. To fix: set Private DNS to "Automatic" or turn it off so all resolution goes through the client config. If you must use Private DNS, choose a server that supports DoH and doesn't pollute results, but domain-level split routing may still fail.

v2flyNG Differences

v2flyNG uses the v2fly core, which differs from v2rayNG's Xray core in config fields. The same subscription can usually be imported into both clients, but some advanced parameters (e.g., extension fields for certain transports) differ in compatibility. When troubleshooting, first confirm the node protocol and transport are supported by the current core, then consider switching cores or clients. The two clients' config data are independent — when reinstalling or switching to the other client, you need to re-import the subscription.

Comparison Itemv2rayNGv2flyNG
CoreXray-corev2fly-core
Background keep-aliveBattery whitelist + auto-start managementSame
Subscription updatesSupports updating via proxySame
Config compatibilitySupports Xray extension fieldsSome extension fields not supported

For the complete mobile troubleshooting checklist, see the tech note "v2rayNG Connected but No Internet: A Step-by-Step Checklist from System Proxy to Routing Rules" — desktop and mobile can be used side by side.

Download v2rayN