troubleshooting / reference

V2Ray Troubleshooting Guide

Narrow down V2Ray client issues layer by layer, from the local app and proxy entry point through the V2Ray core, remote node, DNS, and target service. Covers connection, subscription, performance, and runtime issues in v2rayN, v2rayNG, and v2flyNG.

How this guide is organized: The setup guide covers the main steps for importing a subscription, choosing a node, and starting a connection. Use this page to diagnose issues that appear after connecting. If the initial configuration is not complete, follow the setup guide first, then return to the section matching your symptom.
01 / offline

The client is connected, but webpages will not open

“Connected” only means the client core has started. It does not prove that app traffic is reaching the local proxy or that the remote node can access the destination. First determine whether all websites fail, only some websites fail, or only a particular app is affected.

Start with a cache-free test

Keep one ordinary webpage and one pure IP connectivity test as references; do not rely only on a page that has been open for a long time. Browsers may reuse old connections or retain a failed DNS result. Close every browser window and reopen it, or test in a new private window. Temporarily stop other proxy tools, network accelerators, and traffic-filtering software so that only one program changes the system proxy at a time. If the computer is connected to wired, wireless, and virtual interfaces simultaneously, keep only the interface currently in use to prevent the default route from shifting between exits.

Next, inspect the client’s main window: the intended node should be selected, the core should be running, and the log should not repeatedly show configuration parsing or port-binding failures. In v2rayN, “Set system proxy” and “Start core” are separate actions; the core can run while the system proxy remains disabled, in which case an ordinary browser will not send requests through the proxy. With TUN mode, confirm that the virtual interface was created and that the system is not waiting for a permission prompt. For the principles and complete setup steps, see How TUN mode takes over traffic.

Check local listening ports and app proxy settings

Common local entry points in v2rayN are SOCKS and HTTP listening ports; use the client’s settings page as the source of truth. Do not treat an example port from a guide as your current configuration. On Windows, check from a terminal whether the client process is listening; no result means the core did not establish the entry point. If another process occupies the same port, identify it first, then close the conflicting program or change the local port. See How to resolve a local port conflict for the full procedure.

netstat -ano | findstr LISTENING
tasklist /FI "PID eq process ID"

When configuring a browser or other app manually, the proxy type must match the listening entry. A SOCKS5 entry cannot be entered as an HTTP proxy, and an HTTP entry cannot be placed in a SOCKS-only field. The address is usually 127.0.0.1; do not enter the node server address. If the app offers “Proxy DNS” or “Resolve hostnames through SOCKS,” enable it temporarily for comparison. This sends DNS resolution through the same entry as the app request and helps rule out local DNS issues.

Use direct and proxied results to define the fault boundary

Test ordinary networking with the system proxy disabled. If direct access also fails for every webpage, fix the local network, gateway, or network authentication first; V2Ray configuration is not the first suspect. If direct access works but everything fails after enabling the proxy while the local port is listening, inspect the client log to see which outbound is being used. Connection refused usually means the remote address is reachable but nothing is serving on that port; a timeout points more toward the network path, an incorrect address, or an unreachable node; a handshake failure requires checking the protocol, transport, security layer, hostname, and path.

If only some websites fail, briefly switch routing modes for comparison. If global mode works but rule mode fails, the issue is usually the rule match result rather than the node itself. Check whether domain rules are being assigned too early to direct or blocked outbounds, and review how top-to-bottom matching causes earlier rules to override later ones. If the page loads but images, login, or CAPTCHA fail, check whether the page’s other domains matched different rules. Restore the original split-routing target after troubleshooting; do not rely on global mode long term to hide rule errors.

Finally, check the system clock. VLESS, VMess, TLS, and similar paths can be affected by significant clock drift. Enable automatic time synchronization and verify the time zone. After synchronization, restart the core so new connections perform a fresh handshake. If the same node works on another device but still fails here, compare configuration fields, system proxy status, and security software policies first. If every device fails at the same time, the node side or the current network path is more likely at fault.

02 / timeout

Node latency tests time out or the connection is refused

A latency test is not a single standard. The client may perform a TCP connection test, request a real URL, or run a core-level connection check. Results from these methods are not directly interchangeable. A timeout does not necessarily mean the node configuration is unusable; use the failure stage in the log to narrow it down.

Distinguish test types from real access

A TCP test only checks whether a basic connection can be established to the address and port; it does not validate VLESS, VMess, or other protocol parameters. A real latency test accesses a specified URL through the node, covering the local entry point, remote handshake, outbound request, and target response. It is closer to actual use but is also more sensitive to an unreachable test site, DNS failure, or routing rules. If TCP works but the real test times out, check protocol authentication, TLS, the transport path, and the test URL. If TCP itself times out, check the server address, port, and reachability from the current network first.

Do not run high-frequency tests on every node. Batch testing creates many connections at once, which can hit connection limits on local network equipment and flood the log with repeated errors. Choose one clearly configured node, wait several seconds between tests, and read the log for the corresponding time window after each test. A node name is only an identifier; the actual connection depends on the address, port, user ID, transport, security layer, and additional fields.

Log symptom Typical layer Check first
connection timed out Network path or remote side is not responding Address, port, current network, remote status
connection refused Destination reachable but port refused Port value, remote service listener
TLS handshake failed Security-layer handshake Server name, certificate hostname, system time
unexpected response Transport-layer path Host, path, transport type, and intermediary configuration

Compare fields one by one; do not rely on the node name

When adding a configuration manually, verify the protocol type, remote address, port, user ID, encryption or flow-control settings, transport type, path, Host, server name, and fingerprint-related options one by one. Case, leading slashes, and spaces can all change the result. For example, a WebSocket path usually must exactly match the server-side path. The server name is used during the TLS handshake and should not be left blank merely because the node address is an IP. In a REALITY configuration, the server name, short ID, and public key form one parameter set; mixing fields from different nodes causes the handshake to fail.

If only one node fails after a subscription import, copy that node and compare its fields with the original subscription text. Do not repeatedly overwrite the original node, or you will lose the comparison baseline. If every node in the same subscription times out, try another network, such as switching from a corporate network to a home or mobile network. If the other network works, the client configuration is probably correct and the issue lies with the current network policy, DNS result, or exit route. If all networks fail, update the subscription and confirm that the node details have not changed.

Verify address resolution and dual-stack paths

When the node address is a domain name, the client must resolve it through DNS first. Query the domain from a system terminal and check whether it returns addresses and which address families are present. If it returns only IPv6 while the current network lacks a stable IPv6 route, the connection may wait for a long time before timing out. If multiple addresses are returned, one unreachable address can also make the first connection slow. Temporarily switch to a reliable DNS for comparison or adjust the client’s resolution strategy, but do not permanently pin a subscription domain to an IP because the server address may change.

If a latency value is shown but real access fails, the test path and app path are different. Check whether the test bypassed custom routing, whether the app uses the system proxy, and whether the browser has an independent proxy extension enabled. Finish by using one node to load a real webpage before deciding whether to keep it. Latency ranking is useful only for initial screening; stability, handshake success rate, and real destination access are better indicators of whether a node suits the current network.

03 / subscription

Subscription update fails, imports nothing, or leaves the node list unchanged

Subscription issues fall into four stages: address input, network request, content parsing, and local writing. An “update failed” message alone cannot identify the layer. Check in order whether the subscription address is complete, the request succeeds, the response has a supported format, and the client writes the result.

Check the subscription address first

When copying a subscription address, include the complete scheme, path, and query parameters. Chat apps and documents may recognize only the first part as a link and truncate the parameters; spaces, line breaks, or Chinese punctuation may also be added at either end. Paste it again in the client’s subscription manager and use a short, recognizable subscription name. Do not put a single vmess:// or vless:// share link in the subscription field; those are single-node imports. The subscription field requires an address that returns a collection of nodes.

A subscription service may require valid access credentials. If the link has been regenerated, the old address may open yet return only an error message or empty content. Do not assume a subscription is valid merely because a browser displays some text; an error page can also return a normal HTTP status. Client logs commonly record the request status, response type, or parsing failure location. Look for unauthorized, forbidden, resource not found, too many redirects, and empty response content.

Determine whether subscription requests use direct or proxied access

On a fresh installation with an empty node list, subscription updates usually have to use the current direct connection. Once usable nodes exist, some clients allow subscription updates through a proxy. If a direct update fails but a proxied update succeeds, the subscription service is unreachable over the current direct path; the reverse may mean the current proxy node cannot reach the subscription address. During troubleshooting, do not let “update subscription through proxy” and “automatic subscription updates” run repeatedly at the same time, or the log will mix multiple requests. Disable automatic updates first, then test one path manually.

The system proxy and a client’s internal subscription request are separate concepts. Some clients send update requests through the core, while others use the app process, so the system proxy switch does not necessarily determine the subscription path. Follow the client settings and logs. On corporate networks, campus networks, or networks requiring browser authentication, authenticate with a normal browser first. Without authentication, the request may be redirected to a login page, causing the client to report a format error after receiving HTML.

When an update succeeds but the list does not change

First confirm that you are viewing the correct subscription group. A client may create groups by subscription name, so updated nodes can appear in another group while the current screen still shows the old one. Check filters, search terms, and options such as hiding unavailable nodes. Then look for any change in the node count, names, or update time; if the server returned identical content, keeping the old list is normal. If the log says zero nodes were parsed, check whether the subscription format is supported and whether the response is actually an error message.

v2rayN is for Windows, macOS, and Linux desktops, while v2rayNG and v2flyNG are for Android. Support for subscription extension fields may differ between clients. If the same address imports in one client but produces an empty list in another, do not immediately modify every node. Check whether unrecognized fields belong to an extension format the client does not support, and update to the current client version provided on the download page. After updating, create a fresh test subscription group so leftover fields in the old database do not affect the result.

If nodes are duplicated after a subscription update, the same address was usually added multiple times or the client used an “append nodes” strategy instead of an overwrite. Keep one subscription source, delete duplicate subscription records, and update once more. Do not bulk-delete by node name alone, because different servers may use the same display name. When migrating to a new device, add the subscription again on the new device instead of importing both the old database and the same subscription source; otherwise duplicate records and stale configurations can coexist.

Finally, check the system date, network proxy, and certificate trust. If a browser also cannot open the subscription address, fix the network layer first. If the browser can access it but the client cannot, collect the request time, status, and parsing error from the client log, then address the failing stage. A subscription address is an access credential and should not be pasted on a public page or screenshot; hide the full path and query parameters in troubleshooting screenshots.

04 / performance

The connection works, but speeds are slow or initial loading is delayed

Break performance issues into handshake time, DNS time, time to first byte, and sustained transfer. The latency shown by the client cannot explain download speed or prove that the node is the bottleneck. Establish a direct baseline, then change the node, transport, and routing one at a time.

Create a repeatable comparison test

First disable the proxy and test an ordinary webpage plus a stable file download on the same device and network. Record the general result; there is no need to chase a one-off peak. Then enable the proxy and select one node while keeping the browser, test targets, and time period consistent. Pause system updates, cloud synchronization, video playback, and other high-bandwidth tasks during testing. Weak Wi-Fi, a heavily loaded router, or frequent mobile handoffs can make every node fluctuate, so rule out the local link first.

Distinguish between a webpage that opens slowly the first time and a download that remains slow. Slow initial loading followed by normal performance often points to DNS, TLS handshake, or connection setup time. A download that starts quickly and then drops may indicate congestion, remote throttling, or packet-loss retransmissions. If small pages work but large files are slow, basic connectivity is fine; compare path quality and sustained throughput. Do not draw conclusions from one website, since the target service’s own load and regional routing can change the result.

Compare nodes and transport paths

Choose nodes with a reasonable geographic distance and network path for comparison. Lower latency usually helps interactive use, but it does not guarantee high bandwidth. A slightly slower node with less packet loss may sustain transfers more reliably. Change only the node each time and keep all other settings unchanged. If every node in one subscription is slow while direct access is normal, check the local proxy mode, DNS, and security software. If only one node is slow, replace that node first rather than changing the entire client.

Transport parameters must match the server; do not switch them casually to “increase speed.” WebSocket, gRPC, TCP, and other methods have different connection characteristics, but actual performance depends on the server configuration and network path. An incorrect Host, path, or server name may appear as retries and intermittent failures instead of an immediate error. If the log repeatedly shows connection reestablishment, EOF, timeouts, or handshake failures, restore stability before investigating speed.

Check routing, concurrency, and local processing overhead

In rule mode, a page’s main document, images, scripts, and APIs may match different outbounds. If the main page uses the proxy but static resources fail direct, the result may look like a page that stays blank. Open the client’s routing log or switch briefly to global mode for comparison. If global mode clearly improves the result, inspect the matched rules for the page’s related domains one by one. Start with clear, specific conditions and place broad fallback rules later, so a wide direct rule does not capture requests too early.

TUN mode handles traffic from more processes. If speeds drop after enabling it, check whether system updates, LAN access, and large file synchronization are also being sent through the proxy. Proper LAN and necessary direct rules reduce unrelated traffic over the remote path. Also avoid enabling the system proxy, a browser proxy extension, and another virtual interface at the same time. Duplicate forwarding can create a loop, causing high CPU usage, repeated webpage retries, and a sharp speed drop.

Keeping the client log level excessively high can also increase disk writes, especially with many short-lived connections. Raise verbosity for diagnosis, then restore the normal level and remove oversized old logs after confirming the issue. Security software that deeply inspects every new connection can increase initial load time; without changing the overall protection policy, check whether the client process and local listening connections are being scanned repeatedly.

Slow DNS resolution makes a page wait before the connection starts. Use the DNS section of this guide to check resolution time, and see DNS requests and proxy-chain configuration. If TUN uses FakeDNS, also understand the boundaries of fake-address mapping and domain restoration; see How FakeDNS works for the underlying process. After performance changes, retest at least two targets during two time periods so temporary network fluctuations are not mistaken for a fixed configuration issue.

05 / dns

DNS resolution fails, domains behave unexpectedly, or traffic is routed incorrectly

DNS determines which address a domain resolves to first; routing rules then determine which outbound handles the request. They affect each other: a failed lookup prevents a connection from starting, an unsuitable address can cause a timeout, and converting a domain to an IP too early may prevent domain rules from matching.

Determine whether the issue is limited to domains

If the log shows that the target domain failed to resolve but a known reachable IP responds directly, the problem is concentrated in DNS. If the domain resolves but the connection still times out, check the remote path as well. On Windows, use nslookup; on macOS and Linux, use dig or nslookup to inspect system resolution. Record returned IPv4 and IPv6 addresses separately instead of checking only whether the command completed successfully.

nslookup example.com

dig example.com A
dig example.com AAAA

Normal system lookups do not guarantee that the client’s internal DNS works normally. v2rayN, v2rayNG, and v2flyNG can resolve independently through the core and choose different servers based on routing. If direct browsing works but domains fail through the proxy, inspect the DNS server, query type, and outbound marker in the client log. Sending requests to a DNS server reachable only through the proxy before the proxy is established can create a startup dependency. Conversely, forcing DNS requests that require the proxy to go direct can cause persistent timeouts.

Map the execution order of DNS and routing

Routing rules can match domains, IPs, ports, or processes. Domain rules require the core to retain the destination domain; IP rules may require resolution first. With on-demand resolution enabled, addresses are queried only when an IP condition requires them, reducing unnecessary lookups. If every domain is forcibly resolved before routing and then split by the returned IP, services using dynamic addresses may hit the wrong rule. During troubleshooting, start with simpler DNS settings, confirm basic access, and then add split-DNS servers, domain lists, and address policies gradually.

The following core DNS example is for understanding the structure. Adjust the actual addresses and tags for the current network and configuration; do not replace the complete configuration generated by the client. The key points are that DNS servers can specify an outbound and that the query strategy should match the address families supported by the network.

{
  "dns": {
    "queryStrategy": "UseIP",
    "servers": [
      {
        "address": "1.1.1.1",
        "port": 53,
        "skipFallback": false
      },
      "localhost"
    ]
  }
}

Handle cache, IPv6, and FakeDNS boundaries

After changing DNS, clear the system cache and establish new browser connections. On Windows, run ipconfig /flushdns in an administrator terminal. When using the core’s independent DNS, also restart the client core, because clearing the system cache does not clear the core’s internal state. Browsers may maintain their own host cache, so fully exiting and reopening is more reliable than a normal refresh. If the network supports IPv4 reliably but resolution prefers IPv6, temporarily adjust the query strategy for comparison. Then decide whether to fix the local IPv6 route or have the client prefer the currently reachable address family.

FakeDNS is often used with TUN mode: the app receives a reserved address, and the core restores the original domain from the mapping before applying routing. This preserves domain information, but not every LAN app or special protocol works well with fake addresses. If LAN device discovery fails or an app behaves abnormally when connecting to a fixed IP, exclude LAN domains, private address ranges, and necessary system services from FakeDNS. Do not use a FakeDNS address as a real remote address in rules or manual connections.

If access works but the resolution path is not what you expected, observe the DNS requests made by the app, the DNS used by the client, and the DNS required to connect to the node separately. The node server’s domain must be resolved before the proxy path is established, so it usually needs a directly reachable resolution path. The target website can be resolved through different outbounds according to routing. Mixing these two query types into one complex rule set easily creates a circular dependency. After fixing the issue, verify the resolved domain, the outbound marker in the client log, and a real webpage request. For practical detection methods, continue with Hands-on DNS leak detection and fixes.

06 / system-proxy

The system proxy is enabled, but app traffic is not reaching the client

A system proxy is an operating-system setting that apps can choose to read; it is not forced interception of all network traffic. Browsers usually honor it, while some command-line tools, games, store apps, and software with its own network stack may ignore it. Before declaring it broken, confirm that the target app supports system proxies.

Confirm that the system proxy matches the local listener

The system proxy address should point to the local entry, usually 127.0.0.1 plus the client’s current HTTP port. If the client changes its local port while the operating system retains the old one, enabling the proxy will appear to immediately cut off internet access. An abnormal v2rayN exit can also leave stale settings behind, so after reopening the client, clear the system proxy and set it again from the current configuration. Do not let multiple clients compete for the same port or repeatedly rewrite the system proxy.

On Windows, view the manual proxy in network settings or read the WinHTTP configuration from a command line. WinHTTP and the proxy settings used by ordinary desktop apps are not identical, so a command showing “direct” does not by itself prove that the browser is not using a proxy. On macOS, configure web and secure web proxies for the active network service; switching Wi-Fi services does not necessarily apply settings from the previous service. Linux desktops may use graphical settings, environment variables, or app-specific configuration, and all three should be checked separately.

netsh winhttp show proxy

scutil --proxy

env | grep -i proxy

Identify apps that ignore the system proxy

Command-line tools commonly read HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY environment variables, but some require proxy settings in their own configuration. The proxy type in the environment variable must match the local entry, and its scope must be clear: a variable set only in the current terminal is not inherited by another terminal, while a global variable can leave a dead address behind after the client closes. During diagnosis, set it temporarily for the current session and remove it after testing.

Some apps use UDP, direct sockets, or their own DNS and do not follow the HTTP system proxy. In that case, consider TUN mode so the virtual interface can intercept traffic at the network layer. Before enabling it, confirm administrator permissions, the virtual-interface driver, and routing settings, and exclude LAN addresses so printers, router admin pages, and file shares are not sent through the remote path. TUN is not a substitute for fixing a bad node: if the node handshake itself fails, expanding interception only makes more apps fail at once.

Handle stale proxies, loops, and LAN bypasses

Proxy loops commonly occur when a browser extension points to the system proxy, the system proxy is forwarded by another tool, or the client’s own update request is mistakenly sent back to its listening port. Symptoms include high CPU usage, the same target repeating rapidly in the log, and webpages loading endlessly without results. Disable browser proxy extensions and other network tools, leaving only the system proxy written by the client. Once access recovers, decide whether app-level rules are still needed.

The system proxy bypass list should include the local machine and necessary LAN addresses. Access to localhost, 127.0.0.1, and private-network devices normally should not be sent through a remote path. If the bypass range is too broad, such as a vague wildcard covering many domains, requests that require the proxy may go direct. Every bypass rule should have a clear purpose; after changing it, test one LAN address and one external destination separately.

A normal client exit usually restores the system proxy, but forced shutdowns, process crashes, or insufficient permissions may prevent that. If the client is not running yet the internet is unavailable globally, disable the manual proxy in the operating system first, then restart the browser. If this happens often, check whether the client can write the setting, whether security software blocks it, and whether another program periodically rewrites the proxy. For the complete procedure to synchronize the system proxy after a port change, see Resolving local listening-port conflicts.

Final verification should cover three app types: a browser that reads the system proxy, a tool that connects through its own proxy settings, and an app that requires TUN interception. Together they define the boundary between system proxy and TUN. Do not enable every interception method just to make one app work; choose the smallest setup that covers the target traffic so later routing and troubleshooting remain clear.

07 / runtime

The client will not start, crashes, or the core keeps exiting

The client interface and the V2Ray core are separate runtime layers. A window that will not open usually points to the runtime environment, permissions, or user data; an interface that works while the core exits is more often related to generated configuration, port binding, core files, or security policies. First identify which layer is exiting.

Use startup logs to identify the exit stage

If the client window opens, inspect the log directory and the last lines in the main window first. Configuration parsing errors usually appear immediately after the core starts and identify a field, JSON location, or unsupported option. A port conflict appears as a binding failure. An exit after several seconds may involve TUN permissions, the virtual interface, the network environment, or a specific real request. Do not restart repeatedly before the log is saved. Copy the error text around the event time first, and redact node addresses, user IDs, and subscription parameters.

If the interface will not open at all, check the system Task Manager or Activity Monitor for leftover processes. A leftover process may hold the database or ports and cause the next launch to fail. End it normally, then launch once more; do not repeatedly click multiple launch entries. For desktops, v2rayN is the primary choice. Use the client download page to select a package for the correct operating system and processor architecture. If the first macOS launch requires security approval or network permissions, see macOS installation and permission handling.

Separate user data from program files

A crash after an upgrade does not necessarily mean the program itself is damaged; an old database, theme setting, or custom configuration may be incompatible with the new structure. Back up subscription addresses and necessary settings, then close the client. Do not delete the original data directory immediately. Rename it so the client starts with an empty configuration. If that works, the issue is in the user data. Restore subscriptions and settings gradually instead of copying the entire old directory back at once.

Custom JSON configuration is a common cause of core startup failures. First switch to a normal node configuration generated by the client and confirm that the core runs, then inspect the custom file. JSON does not allow trailing commas; backslashes and double quotes inside strings must be escaped correctly, and field types must meet the core’s requirements. The command below checks basic JSON syntax; replace the filename with the actual path.

python -m json.tool config.json

Valid syntax does not mean the configuration is semantically correct. Missing outbound tags, invalid routing-rule references, duplicate listening ports, and fields unsupported by the current core can all fail during loading. Fix the first error identified in the log; later errors may simply be cascading results of the initial failure.

Check permissions, security policies, and system resources

TUN mode must create a virtual interface and modify routes, so it may exit immediately without sufficient privileges. Disable TUN first and verify that ordinary system proxy mode works. If normal mode works but TUN crashes, check administrator permissions, virtual-interface status, and other VPN-related network drivers. Multiple virtual interfaces modifying the default route at the same time can also leave the core without a working network and cause repeated restarts.

Security software may quarantine core subprocesses, block local port listening, or restrict access to the configuration directory. Review system security events corresponding to the client’s launch time and act on specific records instead of blindly disabling all protection. If the program directory is not writable, log and database creation may also fail. Install the client somewhere the current user can read and write, and avoid running it directly from a compressed-file preview window.

For crashes that occur only after running for a while, also watch memory, disk space, and log size. Excessively detailed logs can grow quickly under heavy connection loads, and low disk space can disrupt configuration writes and updates. Clear old logs, restore the normal level, and reproduce once. If one node triggers the crash, copy it and compare its fields. If even an empty configuration keeps crashing, record the operating system, client name, crash time, and system event details, then reinstall the current client build for the correct architecture. Do not import many subscriptions at once during troubleshooting, or configuration and runtime issues may become mixed.

08 / android

Android connection, background operation, and per-app routing

On Android, v2rayNG and v2flyNG use the system VPN interface to intercept traffic, so their runtime path differs from the desktop system proxy. Common issues involve VPN authorization, background limits, per-app routing, Private DNS, network changes, and battery management.

The connect button does nothing or VPN authorization fails

When starting a connection for the first time, Android displays a VPN confirmation prompt. If it is not confirmed, another VPN service is already active, or a work-profile policy blocks it, the client cannot create the interface. Disconnect other VPN apps, return to the client, start the connection again, and approve the system prompt. A VPN icon in the status bar only means the interface was created; check the client log to confirm that the node handshake succeeded. If the connection stops immediately, inspect the node configuration, current network, and app background permissions instead of repeatedly tapping the start button.

When switching from one client to another, stop the service in the original client before opening the new one. v2rayNG uses the Xray core, while v2flyNG uses the v2fly core; they are different Android options, but they should not establish system VPNs simultaneously. Import the subscription into each client separately for testing and keep the node parameters identical so client differences are not confused with node differences. If reinstalling, use the Android client entry to choose v2rayNG or v2flyNG, and select a package matching the device architecture.

Handle background disconnects and network changes

Battery optimization may restrict the client from running in the background after the screen turns off. Add the client you actually use to the list of apps allowed to run in the background, and permit autostart or background activity. Depending on the device, these settings may be called battery optimization, background usage, power management, or sleeping apps. Adjust only the client in use; there is no need to relax restrictions for every network app. After changing the setting, lock the screen for several minutes, then unlock it and test a webpage and the log to confirm that the service is still running.

Switching from Wi-Fi to mobile data changes the local IP, DNS, and default route. The client usually rebuilds the connection automatically, but old connections may linger briefly. If access fails after a network change, stop and start the service once so the VPN interface binds to the current network again. Frequent switching between networks makes test results confusing; complete verification on one network first, then test the other. If only one network fails, return to the node-timeout and DNS sections to assess that network’s reachability.

Check per-app routing and Private DNS

Android per-app routing controls which apps enter the VPN. With an allowlist, newly installed apps may bypass the client by default; with an exclusion mode, an excluded browser will also bypass the proxy. When only one app fails, first check whether it is selected, then temporarily disable per-app routing for comparison. Once all apps work, restore routing and add apps one at a time. System components, download managers, and external services called by browsers may run in different processes, so selecting only the main app may not cover the complete request path.

Android Private DNS can create another resolution path outside or inside the VPN, depending on the system and client settings. If domains fail while IP access works, temporarily set Private DNS to Automatic and compare, then inspect the client DNS. A browser’s own Secure DNS can also bypass core rules, so keep its default setting during troubleshooting. After confirming that the client DNS works, decide whether to restore a custom system-level resolver.

When LAN access fails, check whether LAN bypass is enabled and whether the app is trying to reach a private address. Some devices block connections outside the VPN by default when a VPN is active, making printers, router admin pages, or LAN services unreachable. Set explicit direct rules for private addresses in the client and ensure that the system is not using a strict option that blocks all non-VPN traffic. After changing it, test a LAN address and an external webpage separately so the direct range does not become too broad.

If a QR import connects unsuccessfully, compare the protocol, address, port, user ID, security layer, server name, and transport path field by field. Camera recognition may truncate long content, and the clipboard may retain line breaks. Subscription imports are generally easier to update than scanning multiple nodes manually, but a failed subscription update still requires the checks in this guide’s subscription section. Keep one reliably reproducible node and test it on both Wi-Fi and mobile data. Failure on only one network indicates a path issue; if both networks fail while the same desktop configuration works, focus on DNS, per-app routing, and transport fields in the Android client.

If an app runs reliably in the background but messages or synchronization are delayed, do not immediately route every app through the proxy. First check whether battery policies restrict the target app, whether it depends on excluded system components, and whether its domains match the expected routes. The key to Android troubleshooting is to verify the system VPN, client core, and app permissions separately: the VPN interface must exist, the core connection must succeed, and the target app must enter the interface. Only all three together form a complete path.

Download the client