V2Ray Troubleshooting Guide

Establish a comparable baseline

First exit the client or disable the system proxy, then use a browser to open a site that is normally reliable while confirming that the local network can obtain an address normally. If direct access also fails, troubleshoot the router, Wi-Fi, Ethernet connection, captive portal, or local network stack first. A proxy client cannot repair an underlying network outage. Once direct access works, restart v2rayN, v2rayNG, or v2flyNG with the same node and routing mode, then open the same site again. This comparison separates an unavailable network from an unavailable proxy path.

On desktop, also distinguish between “the core is running” and “system traffic has been routed into the core.” v2rayN logs should show that the local inbound listener started successfully. If another process occupies the port, the core may exit immediately even though the tray icon remains. Check the local HTTP and SOCKS ports in Settings, then confirm that the browser or system proxy uses those same ports. If a browser proxy extension was configured manually, make sure it is not still pointing to an old port.

1. STEP 01Disable the proxy and verify direct access
2. STEP 02Confirm the core and listening ports
3. STEP 03Verify the system proxy address
4. STEP 04Switch nodes for comparison

Confirm that the local port is actually listening

On Windows, use PowerShell to inspect the relevant port. The example below uses a common local port; replace it with the value shown in the client settings. No output means the port was not opened. If a process is listed but it is not the current client, a port conflict exists. Do not rely on a port number merely looking correct—the listening process is the useful evidence.

WINDOWS / LOCAL LISTENER

Get-NetTCPConnection -State Listen |
  Where-Object { $_.LocalPort -in 10808,10809 } |
  Select-Object LocalAddress,LocalPort,OwningProcess

Get-Process -Id (Get-NetTCPConnection -LocalPort 10809 -State Listen).OwningProcess

On macOS and Linux, use the built-in network tools to inspect listening status. If the result shows only 127.0.0.1, the port is accessible only to programs on the same device, which is normal for standalone desktop use. Allow LAN access only when other devices on the local network genuinely need it. When troubleshooting a single-device issue, do not widen the listening scope first: it adds variables and does not fix an incorrect system proxy target.

MACOS / LINUX / LOCAL LISTENER

ss -lntp | grep -E '10808|10809'
lsof -nP -iTCP:10809 -sTCP:LISTEN

Distinguish proxy, routing, and remote failures by symptoms

Routing mode is the most easily overlooked variable in this symptom. Rule mode selects direct or proxied outbound traffic based on the domain, destination address, and rule set; global mode generally sends more traffic through the proxy outbound. Temporarily switch to global mode for diagnosis. If it restores access, the node is probably usable and the issue is concentrated in rule matching or DNS results. If global mode also fails, continue checking the node and transport layer. Restore the original mode after testing and fix the specific rule instead of treating diagnostic mode as a permanent solution.

Finally, compare with a second known-good node. Change only the node; leave routing, DNS, and the system proxy untouched. If the second node works, the problem is with the original node or its transport parameters. If every node fails, return to local listening, the system proxy, and the client core. Replacing one variable at a time prevents a node failure from being mistaken for a software failure and avoids pointless reinstalls.

Confirm the server address and port first

Open the current node’s edit page and verify the address, port, user ID, encryption options, transport, TLS switch, server name, path, and Host one by one. Nodes imported from a subscription usually should not be rewritten manually. If you changed a field while troubleshooting, compare it with the original subscription content first. The address field should contain only a hostname or address—not a protocol prefix, path, or port pasted alongside it. The port must be a valid number and match the server’s listening port.

When a node uses a domain, first confirm that the device can resolve it. Successful resolution only proves that an address was returned; it does not prove that the port is reachable. On Windows, use Test-NetConnection to test a TCP connection; on macOS and Linux, use nc. Replace the example domain and port with the node’s actual values. If the TCP test fails, adjusting client protocol parameters is pointless—verify the network path, address, and port first.

TCP / REACHABILITY

Test-NetConnection server.example.net -Port 443

nc -vz server.example.net 443

Interpret test results in context. A resolvable domain with a failed port may indicate that the remote service is not listening, the address has changed, an intermediate network is blocking traffic, or local security software is interfering. If the port works but the client still times out, the issue is closer to TLS, WebSocket, gRPC, or protocol authentication. Do not judge a node service by whether its domain opens in a browser: the browser makes an HTTP request, while the node may use an entirely different path and handshake format.

Check that TLS and transport parameters match as a set

In TLS setups, the server name commonly participates in certificate and handshake matching. The node address may be an IP address while the server name still needs the domain specified by the provider; mechanically changing both to the same value can break the handshake. If logs show a certificate-name mismatch, an early handshake close, or protocol-version negotiation failure, restore the subscription’s server name and security settings instead of disabling verification. A badly wrong system clock can also affect certificate validity checks, so restore automatic time and time-zone synchronization first.

For WebSocket nodes, verify the path and Host together. The path usually begins with a slash, and both letter case and trailing characters may be part of server matching. For gRPC nodes, verify the service name. VMess and VLESS fields cannot be judged separately from the transport layer: correct protocol authentication with an incorrect transport path still fails before authentication. If only a few older nodes time out after a subscription update, the server parameters may have changed while the client retained old copies. Delete the old copies and regenerate them from the subscription.

Narrow the failure with comparison tests

Prepare three comparisons: another node in the same client, the same node on another network, and the same subscription on another device. If another node works, the client’s basic path is healthy. If the same node works on another network, the original network path differs. If the same node fails on every device, the remote node or subscription parameters are more likely at fault. Change one condition at a time and record the result; three comparisons usually provide more information than repeated restarts.

Latency tests also need careful interpretation. The connection latency shown by a client is usually the completion time of a particular probe, not the speed of all application traffic. Some nodes may ignore a given probe method while remaining usable, while a fast probe may be followed by failed TLS or application requests. Observe real web requests and runtime logs together. If every node times out, check the system clock, DNS, security policies, and whether the client core loaded correctly instead of editing every node.

For subscription-managed nodes, the final fix should lead back to the subscription source: confirm that the subscription is still valid, check whether node parameters changed after updating, and delete duplicates created by manual edits. If the parameters are correct but the remote node remains unreachable, there is no further local setting to repair. Preserve the stage information from the logs and switch to a working node. This clearly separates an unavailable remote service from a local configuration error.

Confirm the link and update path

Copy the current link from Subscription Management and check that no spaces, line breaks, Chinese punctuation, or duplicate characters appear at either end. Long links forwarded through chat apps may wrap, and copying may capture only the visible portion. Do not decode the link manually before pasting it; the client needs the complete original URL. If the provider changed the subscription address, remove the old entry and add the new one to avoid two similarly named subscriptions where the outdated link is being refreshed.

Next, distinguish “update the subscription through a proxy” from “update directly.” If the current network cannot reach the subscription address directly and the client is set to update without a proxy, the request will fail during resolution or connection setup. Conversely, forcing updates through an expired node also prevents the subscription from loading. In v2rayN, check the proxy option used for subscription updates. On Android, verify the VPN state and per-app rules when the update runs. Use path switching for diagnosis, then keep the confirmed working path.

1. STEP 01Verify the complete link
2. STEP 02Determine whether the request succeeded
3. STEP 03Identify the response content
4. STEP 04Handle parser compatibility

Use the response to identify the failure layer

If the logs include an HTTP status, start by classifying it. A redirect is not necessarily an error, but the client must be able to follow it to the final address. Permission-related responses usually indicate changed credentials, expiration, or access conditions; server errors mean the subscription service is not generating content normally. A successful status still does not guarantee parseable content: a login page, notice page, or gateway error page may also return success, after which the client reports a format error or zero nodes.

Do not paste a subscription link into a public testing page, and never show it in full in a support screenshot. The link often acts as an access credential. During troubleshooting, record only the domain, response status, and error type. When comparing links, compare their length and a few characters at the beginning and end while masking the middle parameters. If client logs print the full URL, remove query parameters before sharing.

Parse failure and an empty node list

When a request succeeds but parsing fails, first confirm the client type. v2rayN is the primary desktop option; Android users can use v2rayNG, with v2flyNG as an alternative using the V2Fly core. Older clients may not recognize newly added protocol fields or transport options. In that case, get the current package from the download page and update the subscription again. Do not remove unfamiliar fields one by one in an old client: the node may appear saveable while still failing during the actual handshake.

An empty node list can also result from subscription groups, filters, or deduplication settings. Clear name filters, view all groups, and confirm that the update targets the current subscription. If deduplication by remark is enabled, several nodes with the same name may be reduced to one. If automatic removal of old nodes is enabled, an empty response may also clear the existing list. Export important settings before updating. During diagnosis, disable automation that changes the list structure so response problems are not mixed with local filtering.

If the same subscription updates on one device but fails on another, first compare client versions, update proxies, DNS, and system time. If every device reports the same error, focus on the link and response side. After recovery, do not stop at an “update succeeded” message: verify that the node count is reasonable, old nodes were replaced as intended, and one randomly selected node can complete a real connection. The subscription path is restored only when request, parsing, and connection all succeed.

Build a comparison with a fixed target

Choose a page or file that is stable over a direct connection and has a reasonably fixed size. Test it with the proxy off, through the current node, and through another node. Wait for each download to finish, stop bandwidth-heavy sync, update, and video tasks, and keep the same network. Do not average results from multiple speed-test pages; different test locations and connection counts add new variables. The goal is not an impressive number but identifying whether the bottleneck follows the node, the network, or a specific destination.

If the first page load is slow but transfer becomes normal afterward, focus on DNS, TCP connection setup, and TLS handshake time. If sustained throughput is low while latency is normal, check node egress bandwidth, congestion, and transport. If speed repeatedly rises and falls with retransmissions, suspect wireless quality, packet loss, or path instability. If only one site is slow, the route from the node’s egress to that site or a site-side limit may be responsible. Separating these patterns is more useful than looking only at client latency.

Check the local path and protocol overhead

Test the direct connection on the same device first. Weak Wi-Fi, a congested band, or background uploads consuming upstream bandwidth can significantly slow a proxied connection. When upstream is saturated, acknowledgements and control packets are delayed; even with download capacity left, pages can feel stalled. Temporarily stop cloud sync, system updates, and large uploads, then retest over Ethernet or closer to the access point. If the direct connection already fluctuates, switching protocols will not produce a reliable conclusion.

Transport encapsulation adds header and handshake overhead, but not every performance issue should be blamed on a protocol name. WebSocket, gRPC, and TLS combinations depend on the actual path and server configuration. Subscription-supplied node parameters are generally designed as a set; do not disable security or change the transport solely to chase speed. An incorrect combination may connect occasionally but trigger retries during sustained transfer. Compare with another fully configured node instead of dismantling the current one.

Routing, concurrency, and test error

In rule mode, different domains may use different outbound paths. A speed-test page, its test endpoint, and its static assets may belong to several domains, so the result can combine multiple paths. Temporarily use global mode to confirm that all related requests pass through the same node. If performance improves clearly, inspect rule matching instead of declaring the node slow. Outbound labels in the logs can show whether each request used the proxy or a direct connection.

Concurrent connection count also changes the result. Some speed-test tools fill the link with many parallel connections, while normal browsing uses many short connections; a high result in the first case does not guarantee smooth browsing. Conversely, low single-connection speed does not necessarily mean low total throughput. For slow pages, watch DNS and handshake time; for slow downloads, fix one download object; for video buffering, also consider content delivery node selection. Use the relevant metric for each scenario instead of explaining every experience with one number.

If every node is slow only on one network and recovers on another, the local access link or network path is more likely responsible. If the same node is slow on every device while other nodes work, switch nodes first. If only a particular destination is slow, inspect the route and destination-side path. After locating the cause, restore background services, routing mode, and test settings that were temporarily changed so the everyday configuration remains appropriate.

Identify system and built-in resolution

In ordinary system-proxy mode, an application may use system DNS to resolve a destination and then pass the address to the proxy. Some applications enable encrypted DNS independently and ignore system settings. Virtual network interface mode may send more DNS requests to the client. When all three paths coexist, the same domain can return different results. Before testing, temporarily disable browser-specific DNS so the path is as simple as possible, then check whether the client logs show the relevant domain.

Use system query tools to establish a baseline. On Windows, run Resolve-DnsName; on macOS and Linux, use nslookup or dig. First query without specifying a server and note the system default result, then compare it with the destination address in the client logs. If the system resolves the name but the client reports failure, inspect the client’s built-in DNS settings. If both fail, check the network’s resolver, system network settings, and domain spelling.

DNS / BASELINE

Resolve-DnsName example.com

nslookup example.com

dig example.com A
dig example.com AAAA

Understand address families and route matching

A domain may return both IPv4 and IPv6 addresses. If the local IPv6 path is incomplete, an application may try IPv6 first, wait for failure, and only then fall back, making the first visit noticeably slow. Use query results and connection logs to confirm the address family actually used instead of disabling IPv6 across the system. If the client offers an address policy, choose one that matches local network capability. Then test domains returning only IPv4 and domains returning both to ensure the change did not introduce a new difference.

Routing rules may match domains or resolved addresses. If domain rules do not use the relevant sniffing or domain-preservation mechanism, an application that supplies only a destination address may not match them. Conversely, relying too heavily on address rules makes routing vulnerable to changing content-delivery addresses. During diagnosis, inspect the matched rule and outbound label in the logs. Temporary global mode can confirm a rule issue, but the final fix should be an explicit domain or address rule.

V2RAY / DNS STRUCTURE EXAMPLE

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

This example illustrates the structure and should not replace the complete configuration generated by the client. The order and domain scope of servers affect where queries go, localhost means the system resolution path, and queryStrategy determines which address types are accepted. Graphical clients may regenerate configuration when saving, so change DNS settings through the provided interface whenever possible. Edit a custom configuration fragment only when the generation logic is understood.

Cache, polluted results, and the verification loop

If an old address still appears after changing DNS, the system, browser, or client cache may not have been cleared. On Windows, use ipconfig /flushdns to clear the system cache; fully exit and reopen the browser; restart the client core. Clear caches only after changing configuration, not repeatedly at every step. If the issue briefly disappears and returns, continue checking where queries actually go instead of treating the cache as the root cause.

WINDOWS / CLEAR SYSTEM DNS CACHE

ipconfig /flushdns

A valid fix requires three checks: system tools return sensible results, client logs show queries taking the intended path, and the real connection uses the expected outbound. Changing only the DNS address without confirming the latter two often produces only a temporary change. After testing, restore the browser’s original settings and check multiple applications so the fix covers the real usage path rather than just one test page.

Check the address, port, and proxy type

After v2rayN sets the system proxy, the Windows proxy page should show the local address and the corresponding HTTP port. Common mistakes include entering the SOCKS port where an HTTP proxy is required, or leaving the old value in the system settings after changing the client port. Record the exact HTTP and SOCKS ports in the client settings and compare them with the system page. The address is usually a loopback address; if it points to a changed LAN address, the proxy may fail after going offline or switching networks.

Automatic configuration scripts, enterprise policies, browser extensions, and other proxy software may compete for control. Typical signs are settings reverting seconds after the client writes them, or different proxy values appearing in the browser and system page. During diagnosis, temporarily disable programs and extensions that modify the proxy and keep only one control source. If the device is governed by a management policy, follow the system notice instead of repeatedly rewriting registry entries.

WINDOWS / CURRENT USER PROXY

Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings' |
  Select-Object ProxyEnable,ProxyServer,AutoConfigURL

The ProxyEnable value indicates whether the manual proxy is enabled, ProxyServer shows the current address and port, and AutoConfigURL indicates whether an automatic configuration script exists. Use these values for diagnosis, but change settings through the system and client interfaces rather than editing the registry directly. If the client exits while the proxy remains enabled, the browser may keep sending requests to a closed local port, causing the internet to appear completely unavailable. Disable the system proxy to restore direct access.

Distinguish system proxy from virtual network interface mode

The system proxy suits applications that follow the operating system’s proxy interface. Virtual network interface mode works at a lower layer and can handle more programs without proxy settings. More interception is not automatically better. If both are enabled or configured incorrectly, traffic may enter the client twice or form a loop. When diagnosing the system proxy, disable virtual network interface mode first and confirm that the browser works through the local HTTP inbound. Evaluate virtual network interface mode separately when you need to cover applications that ignore the system proxy.

Command-line tools often use their own proxy variables. Some read HTTP_PROXY and HTTPS_PROXY but do not automatically use the desktop system proxy. For testing, set the variables only for the current terminal session instead of making them global immediately. Use the client’s actual HTTP port, and clear the variables after closing the client so later commands do not keep targeting a dead port.

SHELL / SESSION PROXY EXAMPLE

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809

unset HTTP_PROXY
unset HTTPS_PROXY

Verify that requests from each application reach the core

Clear the client log and make one identifiable request in the target application. If the corresponding domain or address appears in the log, the application traffic has reached the core; next inspect routing and outbound. If there is no record, the problem remains between the application and local inbound. For browsers, disable all proxy extensions and restart first. For office software and development tools, check their individual network settings. A working browser does not prove that every application uses the system proxy.

A successful fix is not defined by an enabled system switch. It is defined by a request from the target application appearing in the client log and returning successfully through the expected route. If the log remains empty, changing remote nodes will not help. If the request reaches the core but fails, return to the node, DNS, or routing sections. Using the log as the boundary separates “the application did not hand over traffic” from “the core could not deliver it.”

Separate the interface process from the core process

The v2rayN desktop client includes a graphical interface and the core process that handles traffic. If the interface remains usable but every request fails, the core may not have started successfully. If the interface closes outright, inspect application logs and system events. Record whether the crash occurs at startup, when switching nodes, during a subscription update, or when enabling virtual network interface mode. A reliably reproducible action is valuable evidence: “clicking Connect after importing one configuration causes an immediate exit” is more useful than “it crashes sometimes.”

Check Task Manager or Activity Monitor for leftover core processes. An old process holding the port can prevent the new core from starting. Multiple clients may also compete for the system proxy, virtual network interface, or listening port. Exit all related clients, wait for their processes to end, then test with only one client running. If a process will not exit normally, save the logs first and terminate that process rather than rebooting immediately and hiding the relationship.

Handle damaged configuration and permission issues

If the crash began immediately after editing a configuration or updating a subscription, export the current configuration first and create a minimal test environment. Remove recently imported problem nodes, disable auto-start, automatic subscription updates, and virtual network interface mode, and keep one clearly structured node. If the minimal environment starts, restore settings one at a time. Do not copy the entire old data directory into a new installation, or damaged configuration and stale paths will return with it.

Installation-directory permissions can affect writing logs, databases, and core files. Place the desktop client somewhere the current user can read and write without constant elevation. If running from an archive, extract it completely before starting; do not execute it from an archive tool’s temporary view. If security software quarantines the core, the client may retain its interface but lose connectivity. Check the system security record, determine why the file was handled, and obtain a platform-matched client again from the installation packages page.

The Windows desktop edition and the classic WPF edition use different interface technologies. If one interface cannot start reliably in the current system environment, verify the runtime environment and system updates, then compare it with the other desktop entry on the download page. Before switching editions, preserve the subscription URL and routing settings and start the first test in a clean directory without overwriting the original. This helps determine whether the problem is in the interface runtime or triggered by shared configuration.

Logs, resources, and reproducible details

An overly verbose log level can generate substantial disk writes during long sessions, especially when every connection is recorded at debug detail. Use a normal level day to day and increase verbosity only during the short window needed to reproduce an issue. Clear old logs before reproducing, perform one triggering action, and save the result immediately. This reduces exposure of personal configuration data and avoids searching through tens of thousands of old lines for the actual error.

Also watch free disk space, memory usage, and sleep/wake behavior. Low disk space can make database or log writes fail. After waking from sleep, network interfaces may change and old connections or virtual network interface state may not rebuild correctly. If crashes occur only after wake, close and restart the client to test whether the recovery process is involved. If a clean startup also crashes, continue checking configuration and the runtime environment.

Reinstall only after comparing configuration and environment. A correct reinstall test keeps the old directory intact, starts the current package in a new directory, and adds only a minimal configuration instead of importing all old settings. If the new environment is stable, migrate the subscription and routing gradually. If it crashes on the same action, the cause is more likely the system environment, a driver, or a specific configuration format. See v2rayN Windows Installation, Configuration, and Common Pitfalls for further checks on the desktop runtime and leftover system proxy settings.

Confirm the VPN interface and exclusive ownership

When starting a connection, Android should show VPN authorization and the corresponding status. Usually only one app can own the system VPN interface at a time, so another VPN, network-filtering tool, or work-profile network service may prevent v2rayNG or v2flyNG from creating the interface. Disconnect other VPN-type apps and reconnect the current client. If the authorization dialog no longer appears but the status closes immediately, remove the old authorization in Android VPN settings and try again.

Always-on VPN and “Block connections without VPN” are system-level policies. With a correct configuration, they can enforce the intended traffic path, but if the client core fails to start, the subscription expires, or the node is unavailable, they can make the device appear completely offline. During diagnosis, disable both options and confirm that ordinary connectivity returns before testing the client alone. Re-enable them later only if they match the actual network policy; do not mistake system blocking for a client that cannot be turned off.

Remove background and battery restrictions

Some devices restrict background processes after the screen turns off, the user switches apps, or the app has been inactive in the foreground. A typical pattern is that the connection works initially, all requests stall after several minutes of screen-off time, and reopening the client restores access. In system app settings, allow the client to run in the background, set battery usage to unrestricted, and allow necessary background data. Menu names vary by device, but the test is the same: does the process remain after the screen turns off, and does the system keep the VPN state?

Do not enable automatic connection for multiple clients at once. v2rayNG and v2flyNG may be installed for different core scenarios, but run only one during a test. Having both compete for VPN permission can make the status icon flash, drop the connection immediately, or cause the system to return to the other app. Force-stop the client not under test, then clear battery restrictions and auto-start policies for the current client.

Check per-app rules, Private DNS, and network switching

Per-app proxy settings can select which applications enter the VPN or use an exclusion list. Misunderstanding the rule direction commonly results in a working browser while the target app connects directly, or only excluded apps working. During diagnosis, disable per-app routing so every application uses one path. Once connectivity is confirmed, add or exclude applications one at a time. After each rule change, fully stop and reopen the target app so old connections do not continue using the previous path.

System Private DNS and the client’s built-in DNS may operate at the same time. If the Private DNS host is unreachable, domain requests may fail before entering the client. If an app uses encrypted DNS independently, the client’s routing may see only a connection to the resolver. Temporarily set Private DNS to Automatic, disable browser-specific DNS, and test the system resolution path. If access returns, choose either system Private DNS or client DNS according to your needs and avoid overlapping layers of interception.

Switching from Wi-Fi to mobile data changes the local address, default route, and available address families. Some existing connections do not migrate automatically, so the VPN may still show connected while requests stall. After switching networks, wait for the network to stabilize, then disconnect and reconnect the client. If only one network fails, keep the node and client settings unchanged and compare that network’s DNS, IPv6 path, and captive-portal requirements. On public Wi-Fi, complete the web login while connected directly before starting the VPN.

On Android, subscription updates are also affected by background data and the current VPN path. If an update returns an empty list, do not delete the existing nodes immediately. Confirm that the client is allowed network access and that the subscription link is complete, then test updating both while connected and while disconnected. v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core, so support for certain subscription fields may differ. For a valid comparison, keep the same network and subscription; do not change the core, node, and DNS at the same time.

Finally, check the order of events in the application log: did the VPN interface come up, did the core start, did the node complete its handshake, and did DNS return a result? If the interface never comes up, handle system permissions. If the interface is up but the core exits, inspect the configuration and client. If the core runs but the node times out, return to the node section. If only specific applications fail, handle per-app rules. Working within these boundaries avoids clearing the device’s entire network configuration and preserves settings that have already been validated.