v2rayN Troubleshooting and Diagnostic Guide

1. Connected but no internet access

First identify which layer is failing

“Client running” only means the local core process has started. It does not prove that the remote node is reachable or that your browser is using the proxy. The full path runs through the application, system proxy or VPN interface, local listening port, routing rules, DNS, remote node, and destination website. The first troubleshooting step is not repeatedly clicking Connect, but determining whether the break occurs before the local machine or after the node. Disable the client’s system proxy or VPN switch first and confirm that normal network access can open familiar websites. If the direct connection itself is unavailable, fix the Wi-Fi, Ethernet, gateway, or ISP connection first. Restart the client only after the basic network is working.

Next, select a node in v2rayN with a known-complete configuration, temporarily switch routing to Global mode, and enable the system proxy. Global mode is for diagnosis only; it temporarily bypasses complex split-routing rules. If access returns, the node and core are basically working, and the issue is likely in routing rules, DNS, or the bypass list. If access still fails, check the local listener, node reachability, and application proxy scope. After testing, restore the routing mode suited to daily use instead of leaving a temporary diagnostic state enabled.

Check the local listener and application proxy settings

Desktop clients usually provide HTTP, SOCKS, or mixed proxy ports on the local loopback address. If another program occupies the port, the core may fail to start or may start without accepting connections. Open the v2rayN logs and look for clear errors such as “address already in use,” “bind failed,” or “failed to listen.” After finding a port conflict, close the program using that port or choose an unused port in v2rayN settings, then restart the core. Do not change only the browser proxy while overlooking the client listener; both sides must use the same port.

On Windows, PowerShell can check whether a port is listening. Replace the port in the example below with the actual local port shown in the client interface:

Get-NetTCPConnection -State Listen |
  Where-Object LocalPort -In 10808,10809 |
  Select-Object LocalAddress,LocalPort,OwningProcess

Test-NetConnection 127.0.0.1 -Port 10809

If the port is listening normally but only one application cannot connect, check whether that application follows the system proxy. Some programs have their own proxy settings, some read the system proxy only at launch, and others connect directly. For applications with their own proxy options, explicitly enter 127.0.0.1 and the relevant HTTP or SOCKS port for comparison. If an explicit proxy works but the system proxy does not, the node is not the problem; continue to the “System proxy not working” section.

Isolate routing and DNS with a minimal configuration

Common breakpoints in complex configurations include a domain rule matching direct access too early, a destination IP being blocked incorrectly, DNS queries leaving through an unreachable route, or an invalid outbound tag left behind after merging subscriptions. For diagnosis, temporarily disable custom routing and keep only one proxy outbound and one direct outbound. If the minimal configuration works, restore rules group by group and test the same set of addresses after each change. Do not import several rule sets at once and then guess which rule caused the failure.

Logs are the main evidence for determining the outbound path. A normal request usually shows the destination domain or IP, the selected outbound tag, and the connection result. If no new request appears at all, application traffic has not entered the client. If a request appears but immediately fails to resolve, check DNS. If the remote node connection times out, continue to the next chapter. If only some domains fail, check split routing and domain resolution first. The three checkpoints—whether traffic reaches the local port, whether resolution completes, and whether a remote connection is established—turn the vague symptom “no internet” into an actionable problem.

Also check the system clock. TLS handshakes depend on the correct date, time, and time zone; a large clock offset can produce errors saying that a certificate is not yet valid or has expired. Enable automatic time synchronization, fully quit the client, then reopen it and test again. Corporate networks, campus networks, and public hotspots may require portal authentication first. Disable the proxy, complete authentication in the browser, and then enable the client. If the portal is blocked by the proxy, the visible symptom may likewise be that no webpage opens.

2. Node timeouts, refused connections, and handshake failures

Tell the three connection errors apart

“Timeout,” “connection refused,” and “handshake failed” in node tests indicate different stages. A timeout usually means no response arrived within the required time, possibly because the server is unreachable, the port is filtered, the route is lossy, or the address is wrong. Connection refused means the host is reachable but no service is listening on that port, commonly because the port is incorrect or the server is not running. A handshake failure means TCP was established, but the protocol parameters, TLS, transport, or authentication details do not match. Distinguish the stage first so troubleshooting does not devolve into pointless repeated speed tests.

Do not rely only on a single latency test from the client’s node list. Some tests check only TCP establishment and do not cover the protocol handshake; others request a particular URL, making the result dependent on DNS and routing. Check the runtime logs as well, and on desktop systems test basic reachability to the server address and port. Windows can use the following command:

Resolve-DnsName node.example.com
Test-NetConnection node.example.com -Port 443

Here, node.example.com is a documentation example; enter the server domain from your configuration in actual use. If the domain does not resolve, fix DNS first. If it resolves but the TCP test fails, check the network path, port, and server status. If TCP succeeds but the client handshake fails, verify the UUID, password, protocol type, transport, TLS switch, SNI, Host, path, and REALITY parameters.

Check protocol parameters one by one

VMess, VLESS, and Trojan configurations cannot be compared by server address and port alone. Protocol fields must match as a complete set. With VLESS, for example, the user ID, flow control, security layer, transport type, and server name are interrelated; REALITY also requires the matching public key, short ID, and server name. WebSocket configurations generally need the correct path and Host; gRPC requires the matching service name; SNI in a TLS connection should match the server certificate and entry configuration. If a subscription converter truncates even one field, the handshake may fail immediately after TCP succeeds.

When editing a node manually, compare each field with the provider’s complete original configuration instead of filling values in from memory. Differences in capitalization, leading slashes, spaces, and invisible characters can all matter. After copying a UUID or key, paste it into a plain-text editor to check for leading or trailing spaces before entering it into the client. Review node details after importing a QR code or share link, because older formats may not carry newer transport fields. If the same node works on one device but not another, comparing the protocol details side by side is usually more effective than importing it again.

Separate route, network, and server-side problems

If the same configuration connects over mobile data but times out on home broadband, the client configuration is usually valid; check the local network, router, DNS, or upstream path. Conversely, if every network fails at the same stage, a server-side issue or parameter mismatch is more likely. Use a phone hotspot to run a comparison test on the desktop, or switch between Wi-Fi and mobile data on Android. Keep the node, client routing mode, and DNS settings unchanged; replace only the access network.

If the node address uses a domain, also check whether its resolved IP changes between networks. CDNs, dual-stack resolution, and local DNS caches can send two devices to different addresses. Use nslookup or Resolve-DnsName to record the results and compare them with the actual destination IP in the client logs. If the domain returns both IPv4 and IPv6 while the current network has incomplete IPv6 routing, the connection may wait for a long time before falling back. Temporarily preferring IPv4 can help verify the cause, but do not permanently disable system IPv6 without evidence.

If the logs show a certificate name mismatch, an unknown certificate authority, or an inconsistent handshake protocol, do not treat “skip certificate verification” as a normal fix. Check the device time, SNI, server name, and TLS settings first. Temporarily disabling verification can confirm whether the problem lies in the certificate chain, but restore it and correct the configuration afterward. For subscription-provided nodes, fetch the complete configuration again first. If several clients show the same handshake error, the configuration provider needs to check the server entry rather than having you repeatedly change unrelated client options.

Node timeouts can also result from local security software blocking the core process or new outbound connections. Do not begin by disabling all protection; review the block records and confirm that the core executable used by v2rayN is allowed to access the current network. If the client directory moved or the core path changed, an old rule may no longer match. Reauthorize the current path and restart the client. After troubleshooting, verify with a real webpage and file transfer; “latency available” alone does not prove that the full path works.

3. Subscription update failures, empty nodes, or unchanged content

First determine whether the request or parsing failed

A subscription update has two stages: download and parsing. When the request fails, the client cannot retrieve the subscription body, and logs usually show a timeout, name-resolution failure, refused connection, or abnormal HTTP status. When parsing fails, the request may have succeeded, but the response is not a subscription format supported by the client. The result may be an unchanged node count, an empty list, or a format error. Read the update log first instead of judging only from the list. The two problems require completely different fixes.

First check that the subscription URL is complete. Query parameters, capitalization, and special characters may be part of authentication; omitting the final character during copying can invalidate it. The address below illustrates the structure only and cannot be used as an actual subscription:

https://example.com/subscription?token=xxxx&client=v2rayN

If the address passed through a chat tool or document, it may have been wrapped automatically or given extra punctuation. Paste it again in the subscription group settings and check for spaces at both ends. Do not use a web management URL, node-sharing page, or login page as a subscription URL. A page opening in the browser does not mean its response is suitable for client parsing; conversely, a long string of encoded text displayed directly in the browser is often a normal subscription response, not damaged content.

Choose whether update requests use the proxy

The route to the subscription server may differ from the route used for node traffic. Clients usually let you update subscriptions through a direct connection, the current proxy, or the system proxy. If a direct request times out while an existing node still works, route the update through the current proxy. If the proxy node itself is already dead, forcing the update through it creates a loop; use a direct connection or import a working node first. Confirm the actual outbound path in the logs instead of switching options at random.

During a first installation with an empty list, there is no existing proxy available for subscription updates, so first confirm that the subscription URL is reachable over the current basic network. If you already have nodes, select one that actually works before updating. Afterward, check the subscription group’s last update time, changes in the node list, and error logs. If manual updates work but automatic updates fail, check the update interval, device sleep, whether the client stays resident, and whether the proxy core is ready when the task starts.

For cases involving updates that bypass the proxy, expired links, timeouts, or malformed formats, read Six Reasons v2rayN Subscription Updates Fail and How to Configure Automatic Updates. That article focuses on automatic update settings; this chapter focuses on identifying the failure stage from logs.

Handle formats, caches, and group replacement

Common subscription responses include collections of base64-encoded share links, one share link per line, and native JSON configurations. Supported fields vary between clients and cores. A v2rayN subscription can contain several common node types, while v2rayNG and v2flyNG may differ in core capabilities and import fields. If the server returns webpage HTML, a login prompt, error JSON, or empty text, the client cannot parse it as a node subscription. Check the actual response type and confirm the account status and subscription endpoint.

If the logs show that both download and parsing succeeded but the list appears unchanged, check subscription-group filters, alias replacement, and deduplication settings. Some users enable current-group-only display, keyword filtering, or remark-based deduplication, so new nodes may already be imported but hidden by the interface. Clear the search box, switch to the complete server list, and inspect the target group. Do not immediately delete all old nodes; export the current configuration or duplicate the group first, then perform one replacement update to determine whether the content is unchanged or the client’s merge strategy is hiding the difference.

Subscription caching can also produce “update succeeded but content is still old.” Fully exit the client, reopen it, and update manually. If the client offers an option to clear subscription cache or bypass the cache, back up first and then use it. When the system proxy points to the current client, do not use a browser to judge subscription reachability while the core is stopped; browser requests may still target the closed local port. Disable the system proxy first, confirm direct access, and then compare.

Do not set the automatic update interval too short. Frequent requests do not improve node quality and may trigger server rate limits or overlapping tasks during network changes and device wake-up. Set a reasonable interval based on how often the subscription actually changes, and update manually when needed. If only certain new protocol nodes fail after an update, return to the node details, verify the fields, and confirm that the selected client core supports the configuration. For format differences, read V2Ray Subscription Formats and Conversion Explained.

4. Connected but webpages and downloads are slow or speeds fluctuate

Measure latency, throughput, and stability separately

Low latency does not mean high download speed. Latency measures the time for one round trip; throughput depends on link capacity, congestion, packet loss, server load, and TCP behavior. Stability reflects how often a continuous connection jitters or retransmits. Results in the client’s node list are useful only for initial screening and cannot replace real access tests. To diagnose speed issues, keep the same device, access network, test period, and destination, then compare direct access, one node, and another node separately. This avoids mistaking the destination website’s own load for a client problem.

Close other downloads, cloud sync, system updates, and video playback before testing the first load of an ordinary webpage, continuous image loading, and one legitimate file download. If every node is slow on the same network but works after switching to a phone hotspot, check local broadband, Wi-Fi interference, router performance, and the upstream path first. If only one node is slow, the node route or load is usually responsible. If the browser is fast but a specific application is slow, check whether it uses the same proxy, uses UDP, has its own DNS, or limits concurrent connections.

Check whether routing is sending traffic the long way around

Incorrect split-routing rules can send traffic that should use a direct connection through a remote node, or make requests that need the proxy try direct access before timing out and falling back. Both cases slow the initial page load. Inspect the logs to see which outbound tag slow requests ultimately match, especially domain rules, IP rules, and the default rule order. Routing usually matches from top to bottom or according to the core’s priority rules; an overly broad rule can hide later, more specific rules. Copy the existing rule set before editing, then validate with a small number of domains instead of rewriting the entire configuration.

Here is a simplified rule for understanding split-routing structure. The snippet shows the relationship between geosite and the default outbound; actual tag names must match the outbounds already present in the client:

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["geosite:cn"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

domainStrategy controls the relationship between domain matching and resolution. With AsIs, the original domain is matched first, avoiding unnecessary early resolution; IP-based routing may resolve the domain later. There is no single setting that suits every network, so choose based on the rule structure. Reload the configuration after changing it and confirm in the logs that the new rules are active.

Troubleshoot MTU, UDP, and multiplexing

If webpages open but large files stall, video buffers intermittently, or some requests pause for a long time, the path MTU may be involved. VPN interfaces, tunnels, and some access networks add encapsulation overhead. Packets that are too large to fragment correctly can produce normal small requests but failed large transfers. On desktop, first compare system-proxy mode with virtual-interface mode. If system-proxy mode works but virtual-interface mode does not, check that mode’s MTU, driver, and routing table. Do not lower the MTU drastically based on guesswork; adjust it gradually and observe whether large transfers become stable.

UDP is important for DNS, real-time communication, and some newer transports, but support varies by node and network. If intermittent problems begin after enabling UDP, first confirm at the application layer that it is actually needed, then check the core logs for UDP timeouts. Disabling UDP for one application and disabling it globally are different operations; the latter can change DNS and other programs’ behavior. For webpages using QUIC, the browser may also fall back when UDP is unstable, causing a slow initial load followed by normal performance.

Multiplexing can reduce repeated connection setup in some scenarios, but more is not always faster. On a lossy route, too many requests sharing one connection can affect one another; a server configured differently may also cause handshake failures. When diagnosing speed fluctuations, temporarily disable multiplexing for comparison instead of changing concurrency, caching, DNS, and transport at the same time. If stability improves, decide whether to re-enable it based on the node server’s capabilities.

Check local resources and wireless conditions

The core performs encryption, decryption, route matching, and log writing. Older devices, power-saving modes, and excessive verbose logging can all limit throughput. During a transfer, watch CPU, memory, and disk usage. If one core remains heavily loaded, the bottleneck may be local processing. If resource usage is low but throughput periodically drops to zero, packet loss, wireless interference, or server congestion is more likely. Android devices are also affected by battery policies and background limits; see the mobile section.

Wi-Fi signal bars do not fully represent link quality. Same-channel interference, an overheated router, device distance, and automatic band switching can all cause jitter. When possible, test over Ethernet first. If wireless is the only option, move closer to the router and pause high-bandwidth activity on other devices. If speeds drop at the same time every day while client settings remain unchanged, record the time, access network, and node differences instead of repeatedly reinstalling the client. Stability requires repeated, low-interference comparison data, not a single peak result.

5. DNS resolution failures, suspected DNS interference, and inconsistent addresses

Determine whether the problem is the domain or the connection

DNS problems often appear as “server not found,” resolution errors in the logs, a node that connects by IP but times out by domain, or some domains opening at the wrong address. First distinguish “no resolution result” from “resolved to an unusable address.” The former usually involves an unreachable DNS server, incorrect proxy DNS settings, or a faulty system cache. The latter may come from caching, split-routing policy, IPv4/IPv6 preference, or different DNS responses. Simply replacing DNS addresses does not explain the cause; record the current resolution result first.

On Windows, use the following commands to view system resolution and results for a specified record type:

nslookup node.example.com
Resolve-DnsName node.example.com -Type A
Resolve-DnsName node.example.com -Type AAAA
ipconfig /displaydns

On macOS and Linux, use nslookup, or dig where available. Compare the destination IP in the client logs to determine whether the request used system DNS, the client’s built-in DNS, or remote resolution. If the command-line result is normal but the client fails to resolve, check the client DNS configuration and outbound tag. If both system and client resolution fail, check the network-provided DNS, router forwarding, and the local firewall first.

Understand local and remote resolution

A system proxy mainly forwards an application’s HTTP or SOCKS traffic; the application’s DNS queries do not necessarily go through the proxy automatically. Some browsers use their own secure DNS, some programs call the system resolver directly, and SOCKS clients may resolve locally before sending only the IP to the proxy. As a result, different applications on the same device can receive different addresses. Confirm whether the application passes a domain or an already-resolved IP to the proxy, and check whether the browser’s built-in DNS settings override the system policy.

Virtual-interface mode can usually take over a wider range of traffic, but it still requires correct DNS hijacking, routing, and exclusion rules. If every domain fails after enabling it while direct IP access responds, the virtual interface has taken over traffic but DNS requests are not reaching a usable resolver. Check the client-generated DNS inbound, virtual address range, and routing table, and make sure the DNS server itself is not sent through an incorrect outbound and caught in a loop. After changing virtual-interface settings, stop the core, wait for the interface to be released, and start it again.

Remote resolution suits cases where the proxy exit should determine the domain address; local resolution is often better for services that return a nearby address based on the local network. Neither is inherently superior. If routing chooses an outbound by domain first, preserve the original domain information. If rules depend on IP sets, resolve at the appropriate stage. When several DNS servers are configured, define each server’s matching domains, query outbound, and failure fallback clearly to prevent queries from looping between direct access and the proxy.

Handle caching, IPv6, and Fake DNS

After changing DNS, old records may remain in the operating system, browser, or client cache. On Windows, run ipconfig /flushdns to clear the system cache, then fully exit and reopen the browser and client before testing. Clearing the cache removes stored results but does not fix incorrect routing or DNS settings. If the record quickly becomes wrong again, inspect the actual query path. Check the browser’s own cache and secure DNS separately rather than relying only on the system command.

On dual-stack networks, a domain may return both A and AAAA records. The system chooses the connection order based on network status and address-selection policy. If a router advertises IPv6 but the upstream path is incomplete, an application may wait for IPv6 to time out before falling back to IPv4, making the initial page load slow. Query A and AAAA separately and observe the addresses actually attempted in the logs. Temporarily preferring IPv4 can help verify the cause, but the final fix should address router IPv6, proxy outbound, or client domain policy instead of permanently hiding the problem.

Fake DNS returns reserved addresses to applications, then the client restores the original domain for routing. It works well with virtual-interface takeover, but the reserved address pool must not conflict with a LAN, corporate network, or another VPN. If enabling it makes LAN devices unreachable, causes a specific application to detect abnormal addresses, or loses mappings after a restart, check the address pool, excluded domains, and cache lifetime. LAN printers, router management domains, and internal business domains usually need local resolution or direct access according to the actual network.

After fixing DNS, test a node domain, an ordinary webpage domain, and a LAN domain. Testing only one public website does not cover subscription updates, node entry points, and local-device access. If the issue affects only one application, check whether it has its own DNS. If multiple devices behave the same way on one router, inspect the router’s DNS forwarding and IPv6 first. If the problem occurs only when the client is enabled, verify the core DNS, routing outbound, and virtual-interface settings one by one.

6. System proxy enabled but the browser or app does not use it

Confirm the proxy values in the operating system

v2rayN’s “System Proxy” switch points the operating system’s proxy address to a local listening port. Core runtime and system proxy are separate states: if the core is running but the system proxy is off, only applications with explicit proxy settings use the client; if the system proxy is configured but the core is stopped, applications connect to a local port with no service. Confirm all three: core status, local port listening, and system proxy address.

On Windows, view the manual proxy address and port in the system network proxy settings, or inspect the current user’s related configuration with PowerShell. The key is not memorizing the registry location, but confirming that the port shown in the interface matches the port v2rayN is actually listening on. If switching configurations changes the port, the old system proxy may still point to the previous one. Turn the system proxy off first, then enable it again from the client; this is usually more reliable than editing several locations manually.

On macOS, proxy settings are stored per network service, so Wi-Fi and Ethernet may have separate configurations. After switching access methods, the client may have updated only the old service, leaving the new connection without a proxy. Linux desktop support varies: some applications read desktop settings, some read environment variables, and others use their own network configuration. Therefore, “system proxy enabled” does not guarantee that every desktop application follows it.

Handle browser cache and independent proxy settings

Browsers usually read the system proxy, but extensions, enterprise policies, secure DNS, and launch parameters can override it. If the browser does not use the proxy, create a temporary profile without extra extensions for comparison, or check whether the browser network settings explicitly specify another proxy. Fully exit and reopen the browser after changing the system proxy, because some programs read it only at launch. If the new profile works, the issue is in the original browser configuration, not the v2rayN node.

You can explicitly specify the local proxy from the command line to verify that the core accepts requests. The port below is an example; replace it with the client’s actual HTTP port:

curl.exe --proxy http://127.0.0.1:10809 https://example.com/
curl.exe --socks5-hostname 127.0.0.1:10808 https://example.com/

If the explicit proxy works but the browser fails, the node, core, and local listener are all working; continue checking the system proxy path. If both commands fail, check whether the client logs received a request. No log entry usually indicates a port or security-software issue; a request followed by a connection failure points back to the node, DNS, or routing sections. With --socks5-hostname, the SOCKS proxy resolves the domain, which is useful for comparison with local resolution.

Understand bypass lists and PAC behavior

System proxy settings usually include a list that bypasses local addresses, LAN ranges, or specific domains. An overly broad bypass rule sends the target request directly, making the proxy appear ineffective. Check for overly broad wildcards, incorrect domain suffixes, or a test website included in the direct-access list. LAN addresses usually should bypass the proxy, but the exact range must match the real network. Removing every bypass entry is not a long-term solution, as it may disrupt router management pages, printers, and internal services.

PAC mode uses a script to decide whether each request uses the proxy or goes direct. A browser may cache the PAC file, and an unreachable script URL may cause it to fall back to direct access. For diagnosis, temporarily switch to a fixed system proxy. If access returns immediately, focus on PAC retrieval, caching, or matching rules. Restore PAC after fixing it and test proxy domains, direct domains, and LAN addresses. For the relationship between system proxy, Global mode, and bypass rules, read System Proxy, Global Mode, and Bypass Rules Explained.

Permissions, stale state, and proxy loops

After an abnormal client exit, the system proxy may remain configured. If the next launch uses a different port, the browser continues connecting to the old address. When the internet stops working after quitting, disable the manual proxy in system settings first, then check whether an automatic configuration script is still enabled. Start the client, confirm that the core works, and let the client write the settings again. Do not let multiple proxy clients manage the system proxy at the same time; they may overwrite each other and create a mismatch between state and interface.

Proxy loops commonly occur when the client updates subscriptions, checks connectivity, or downloads rules through its own stale system proxy. Logs may show repeated connections to a local port, unanswered requests, or every network operation failing after the core stops. Define clearly whether each internal request uses direct access or the current proxy, and ensure the client does not depend on an exit that has not been established yet. When switching nodes, wait for the new core to start listening before triggering operations that require a proxy.

Some applications do not support system proxies or proxy only HTTP traffic. They need a SOCKS or HTTP address entered in their own settings, or a virtual-interface mode in a suitable desktop environment. Before switching to virtual-interface mode, understand its permission, DNS, and routing effects; it is not a universal system-proxy switch. If only one program fails, check that program’s proxy support documentation first. If every program fails, inspect the system and client layers.

7. Client will not start, core exits, or frequent crashes

Separate the UI process from the core process

v2rayN uses a graphical interface for configuration management and calls the Xray or V2Fly core to handle traffic. If the interface opens but stops immediately after connecting, the core likely failed to start. If the interface itself will not open, the window closes instantly, or a configuration page crashes, check the runtime environment, configuration files, permissions, and UI-related components. Their logs and recovery paths differ. First record whether the crash occurs when opening the client, starting the core, loading a subscription, or beginning a transfer.

If the interface remains usable, open the log directory and keep the errors from immediately before and after this launch. Common core startup errors include invalid JSON syntax, missing outbound tags, port conflicts, unreadable rule files, and unsupported configuration fields. Do not capture only the final line; the root cause often appears earlier during configuration parsing. If the logs are too verbose, temporarily set the level to warning or info and reproduce the issue once to prevent normal connection records from hiding the key error.

Verify that the generated configuration is complete

After manually adding routing or migrating an old configuration, errors in commas, quotation marks, or brackets can cause the core to reject the file. Standard JSON does not allow comments or a trailing comma after the last array item. The example below is a structurally complete minimal illustration for understanding the hierarchy; do not replace an existing node configuration with it directly:

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

If the client can display the generated configuration, focus on the field path identified in the log. Do not duplicate top-level objects already generated by the client in custom fragments, and do not reference a nonexistent outboundTag. When copying a configuration from another client, confirm that the target core supports the same fields. Xray and V2Fly share a common foundation but have different capabilities; read Xray Core vs. V2Fly Core: Key Differences for details.

Handle permissions, paths, and security-software blocks

Without write permission in the client directory, the program may be unable to save configurations, update core files, or write logs. On desktop systems, place the client in a location where the current user has normal read/write access, and avoid temporary or automatically cleaned directories. Do not rely on administrator privileges permanently. If normal permissions fail, identify the specific file or operation being denied and correct the directory permissions. Running with elevated privileges can change file ownership and cause normal launches to fail afterward.

Security software may block a newly downloaded core process or classify updated files as unauthorized. Review system security and quarantine records and confirm the exact blocked file path. Grant only the required execution and network permissions to the trusted installation directory; do not disable the entire protection system. If the v2rayN interface starts normally but the core file disappears immediately, handle the quarantine rule first, then download the client again from the Windows download page.

If the path contains special characters, cloud-sync placeholder files, or an excessively deep directory structure, the external core and rule files may not be read correctly. Move the client to a short, stable, writable user directory for comparison. Exit the program before moving it; afterward, select the core path again and check whether the subscription, log, and rule directories still point to the old location. Do not move the directory while the program is running, as the interface’s save location and the core’s working directory can diverge.

Recover a damaged configuration without losing everything

If the interface crashes immediately after updating a subscription or changing routing, copy the entire configuration directory as a backup first. Then try moving aside the recently changed custom rules, UI state files, or one subscription group. Start with the smallest change; do not delete all configuration at once. Once the client opens again, import server and routing settings one by one, restarting after each import. This identifies the damaged file while preserving the rest of the working data.

Frequent crashes can also result from low memory, oversized rule sets, or continuously growing logs. Check memory, disk space, and log size before a crash. Large numbers of duplicate rules increase startup parsing time, and an unusually long line in a custom domain list can add extra load. Remove duplicates, split rules by purpose, and retain only necessary logs. If crashes occur only while handling many connections, reduce application concurrency for comparison and check whether the system recorded the process being terminated by resource limits.

After recovery, add features back in this order: interface startup, core listening, a single-node connection, subscription updates, and custom routing. Keep each step working before continuing. If the error appears only with a custom fragment, rewrite it using fields supported by the current core instead of reusing a complete configuration exported by an older client. If reinstallation is necessary, choose the package for the current platform from the Download Center, and verify that a blank configuration starts normally before importing old data.

8. Android connection drops, background failures, and per-app routing

Confirm VPN permission and system conflicts

v2rayNG and v2flyNG usually take over application traffic through Android’s VPN interface. Android displays a VPN authorization prompt on the first connection. If authorization was denied or revoked, or another VPN is occupying the interface, the client cannot establish it. A VPN icon in the status bar only proves that an interface exists; check the client logs to confirm that the core started and loaded the selected node. If tapping Connect immediately disconnects, check whether Android says another VPN is running, then check whether a work profile, enterprise management, or security app restricts VPN permission.

Android generally allows only one primary VPN service at a time. Ad blockers, enterprise VPNs, network accelerators, and other proxy clients can conflict with v2rayNG or v2flyNG. Fully stop other apps using the VPN interface instead of merely dismissing them from recent apps. “Always-on VPN” and “Block connections without VPN” in system settings also affect switching. If always-on VPN is bound to another app, the new client may not receive permission.

When choosing a client, note that v2rayNG uses the Xray core, while v2flyNG is based on the V2Fly core. They overlap on common configurations, but support for some protocols and transport fields differs. If only certain nodes fail after importing a subscription, first check whether they depend on capabilities of a particular core; do not copy the same configuration between the two clients unconditionally. To install or replace a package, open the Android download page.

Handle battery optimization and background limits

Connections that drop after the screen locks or fail soon after switching apps are usually related to battery optimization and background limits. The system may pause the client process, restrict background networking, or reclaim the VPN service. In the app’s battery settings, allow background activity and remove strict power-saving restrictions using the options provided by the device. Some devices also offer auto-start, background pop-up, or task-lock settings. The goal is to let the VPN service keep running; unrelated permissions are unnecessary.

After changing battery settings, restart the client and run a complete test: access a webpage with the screen on, lock the screen for several minutes and test again, then switch between Wi-Fi and mobile data. If it fails only after locking, focus on background policy. If it fails after a network switch, the VPN interface may not have been recreated, the old DNS cache may remain, or the node connection may not have redialed. If logs show network loss without a new default network, the client did not receive the system network change in time.

When system memory is tight, background processes may also be reclaimed. Many resident apps, games, and browser tabs increase the likelihood. Check whether the client notification disappears during the interruption. A disappearing notification usually means the service stopped; a notification that remains while access fails points more toward a tunnel, DNS, or node connection failure. A persistent notification can help the system treat the VPN service as a foreground task and distinguish service termination from link failure.

Check per-app routing and bypass settings

Android clients can decide per app whether traffic goes through the VPN, bypasses it, or is proxied only for selected apps. Incorrect list settings can make the browser work while other apps connect directly, or leave only a few apps offline. Temporarily disable per-app routing so all ordinary apps enter the VPN and confirm that the basic connection works. Then restore the allowlist or blocklist and verify target apps one by one. Do not enable “proxy selected apps only” together with the opposite bypass logic.

System components, download managers, and embedded webpages may send requests from different processes. A download started inside an app may not be executed directly by that app’s package, so selecting only the main app can allow login while downloads fail. Check per-app statistics or logs to confirm that the actual traffic enters the VPN. For apps that depend on LAN devices, allow local-network bypass when needed; otherwise casting, printing, and router-management functions may stop working.

Per-app proxying and core routing operate at two different layers. The former decides whether app traffic enters the VPN; the latter decides whether traffic inside it uses the proxy or a direct route. If the app never enters the VPN, changing geosite or IP rules has no effect. If it has entered but the destination domain matches the wrong outbound, adjust core routing. When the logs contain no request from the app, check per-app routing first; when a request appears with the wrong outbound, inspect routing rules.

Network switching, Private DNS, and hotspot sharing

When switching from Wi-Fi to mobile data, the local address, DNS, and MTU may all change. The client must rebind to the default network and restore the tunnel. If the status says connected but webpages stall after switching, pause and reconnect before deleting nodes. If this happens often, check whether the client allows automatic reconnection after network changes and whether the system restricts background networking. On dual-SIM devices, also confirm that the selected data SIM matches the system’s default network.

Android’s Private DNS setting may run alongside or conflict with the client’s built-in DNS. If domains fail while IP access works, record the current Private DNS mode and temporarily switch to Automatic for comparison. If Automatic fixes it, check the reachability of the Private DNS host and the client’s DNS routing. If nothing changes, the issue is more likely inside the VPN’s resolution path. Do not treat disabling Private DNS as the final answer; choose the setting that matches the actual resolution path after testing.

When a device shares a hotspot, whether downstream traffic passes through the phone’s VPN depends on system capabilities and the client’s forwarding method. The phone’s own connection status cannot prove it. If the phone can access the internet but a computer connected to its hotspot cannot, first confirm that the downstream device can connect normally, then check whether the client explicitly supports hotspot traffic forwarding. Without that forwarding capability, install the desktop client independently on the downstream device instead of repeatedly changing the phone’s node.

Finally, verify in a fixed order: remove strict battery restrictions, stop other VPNs, disable per-app routing, select a confirmed working node, and test a webpage with the default routing. Then lock the screen, switch networks, and restore per-app routing one setting at a time. If the basic state still fails, use the logs to determine whether the issue is resolution, connection, or handshake, then return to the corresponding earlier section. If the basic state works but failure returns after restoring one setting, that setting is the clear troubleshooting entry point. Layered restoration preserves subscriptions and routing more reliably than repeatedly clearing app data.