01 / Connection basics
No internet access
Restore direct access first, then check the local proxy and active server. If direct access also fails, troubleshoot the underlying network.
Disable traffic capture and test direct access
Note the last thing you did before losing internet access: switched servers, resumed from sleep, or updated the client. On desktop, right-click the v2rayN tray icon and select “Clear system proxy” under “System proxy.” If TUN mode was also enabled, turn it off for now. Close and reopen your browser, then visit two sites that normally work without a proxy. Testing two sites helps rule out an outage affecting just one site. On mobile, disconnect the client's VPN first, then run the same test in a browser.
If direct access still fails, check whether the system has a network address and whether the network requires you to sign in first. Public Wi-Fi can show as connected before web authentication is complete. In an office, the network may require a proxy already configured on the system; restore the settings provided by your administrator after clearing them. Disabling the proxy isn't always the right fix. If the system normally connects directly and only one device is affected, try the same site on another device on the same network. If both fail, check the gateway or network connection; if only one fails, review that device's existing network settings.
If direct access works, check the local listener
Return to the v2rayN main window, select a known-working configuration, and set it as the active server. A highlighted row only means it's selected; check the window's status area to confirm the active server changed. Then review the latest startup messages. If they report a port conflict, configuration read error, or core startup failure, address that first. An open window only means the graphical interface is running. For the proxy entry point to work, the core must start and listen on the port specified in the current settings.
Leave TUN off for now. In a test app that supports manual proxy settings, enter the local listening address and port shown by the client. Check the proxy type: for an HTTP proxy, use the client's HTTP or compatible mixed entry; apps that only support SOCKS need the corresponding entry. Don't enter the remote server address in the system proxy settings. If the app still fails, note whether it reports a connection refusal, timeout, or error from the destination. A refusal points first to the local listener; a timeout may involve the active server or network; for a destination error, check whether the response came from the proxy or the destination service.
Choose the next step based on what is affected
If manual proxy settings work but the browser still can't connect after you select “Automatically configure system proxy,” go to System proxy not working. If only one server fails, keep the working ones and use Server timeouts to check the port, handshake, and destination access in turn. If only domain names fail, use DNS resolution issues to identify which component is resolving them. Don't overwrite the current setup by importing a new subscription during troubleshooting. Note the error time, the active server's custom remark, and the affected app. Then retry once and check the logs that correspond to that request.
After recovery, verify both directions: confirm apps that need a proxy can connect, then clear the system proxy and make sure services that should connect directly still work. If the network only works while the client is running, check whether the system proxy still points to a local port that has since closed, and confirm TUN has been released. A restart may make the problem disappear temporarily, but won't tell you what went wrong. Record whether direct access returned after clearing a stale proxy or proxy access returned after the core resumed listening, so you can start at the right layer next time.
02 / Ports and handshakes
Server timeouts
Start by identifying what was tested. A reachable port doesn't mean the protocol handshake succeeded, and a timed-out test doesn't prove that every destination is inaccessible.
Check whether one server, a group, or all servers are timing out
In the v2rayN server list, compare two entries: the one that just failed and another you have recently used successfully on the same device. Ideally, they shouldn't be two remarks for the same entry point. Test just these two to avoid flooding the local network or triggering server-side connection limits by testing an entire group at once. If the latency shown in the list is from an earlier test, run a fresh test and note its type and time. Don't use an old result to judge current connectivity.
Several servers in the same group may share an entry-point domain, account, or transport settings, so their failures aren't independent. If servers across different groups and entry points all fail, check the core startup messages, device time, and network first. If one entry point keeps failing while another configuration using the same routing mode can open the same page, check the failed entry's service status and settings; there's no need to change global settings. If none have ever connected, follow the import and server selection steps to verify the basics before deciding whether the new configuration is incompatible or the network path is at fault.
Interpret test results by layer
| Test | What it tells you | Check this first if it fails |
|---|---|---|
| System ping | Whether the destination responds to network-layer probes; does not test the proxy port | Whether the destination allows replies, then test the relevant transport |
| TCP connection test | Whether a connection can be established from this device to the specified TCP port | Entry-point domain, remote port, and network path |
| Real connection test | Whether the proxy can reach the address used for the test | Core logs, handshake settings, and test destination |
A TCP test only applies to entry points that require a TCP connection; it can't replace testing real traffic over UDP. A real connection test goes beyond the remote port: it also checks the protocol handshake, outbound forwarding, and the test destination's response. A test address may be unavailable, change how it responds, or restrict requests. The interface may report a timeout even when apps can still reach their actual destinations. If that happens, use the same active configuration to visit two destinations you actually use. If both work, the issue is with the test destination.
Use logs to distinguish connection failures from handshake failures
With the server still active, make one real request and check the error logged at that time. If the log says the server address couldn't be resolved, the remote port hasn't even been reached yet; check the entry-point domain in the DNS section. For a connection timeout, check for a mistyped port, confirm the server is listening, and see whether switching to another network that permits this traffic changes the result. A connection refusal means the attempt was explicitly rejected. Check the service on that port and the entry-point address instead of simply increasing the timeout.
If the port is reachable but the handshake fails, compare the protocol, transport, TLS status, server name, and transport path against the details from your configuration source. The connection address and TLS server name can differ; don't assume they must match. If the error mentions certificate validity, sync the system date, time, and time zone. Don't disable certificate verification to hide the error. If the same configuration handshakes successfully on another device, confirm that both devices use the same entry point, core, and transport settings—not just entries with the same name.
Make sure you fixed the original connection path
After finding the cause, use the original active server to make another real request. Confirm the original error no longer appears repeatedly in the message area, then retest latency. If the server has just moved and its address changed, update the affected group from a trusted source, verify the new entry point, and then switch the active server. A subscription update only fixes the problem if the new configuration actually replaces the failed port. If the error is unchanged, use the logs to keep tracing the entry point or handshake; repeatedly updating the list isn't a substitute for diagnosis.
03 / Requests and imports
Subscription update failures
First confirm that the field contains a subscription URL, then check separately whether the request succeeded and whether the response can be imported.
Check the group and URL without overwriting the existing configuration
On desktop, open “Subscription groups,” then “Subscription group settings,” and select the group that reported the error. Check that “Remark” and “URL” refer to the right group, then confirm that updates are enabled. Matching remarks don't guarantee matching URLs, so it's easy to select the wrong group when managing several. Paste the entire URL into the “URL” field, paying particular attention to trailing query parameters and newlines copied with it. If the URL contains access credentials, check it only in the client. Don't paste it into online parsing tools, search boxes, or public reports.
Share links starting with vmess:// or vless:// usually represent a single server configuration. Import them from the clipboard instead of entering them as a subscription URL. Don't use the provider's sign-in or subscription management page as the subscription endpoint either; opening that page in a browser only shows that the page is reachable. In v2rayNG, open “Subscription groups” in the sidebar to check the saved URL, then return to the main list and update the subscription. Menu labels may vary slightly by language or version; see the illustrated subscription import steps for both clients. Keep any working configurations before updating so you don't lose servers to compare against.
Use one manual update of the current group to pinpoint request failures
In v2rayN, open “Subscription groups” and select the option to update the current subscription. If both “through proxy” and “direct” options are available, choose based on your existing connection: use direct access if the subscription service is reachable without a proxy. If only the proxy path works, first confirm the active server itself is working, then update through the proxy. Updating through the only active server if it has already failed creates a circular dependency. Instead, use a network that can reach the subscription service or another working configuration. There's no need to change every group to the same update method first.
Check the log immediately after starting one update. If no connection is established, check DNS resolution for the subscription domain and the network path. If there's a status code, handle it according to the response. For unauthorized or forbidden responses, check whether the URL was replaced or access has expired, then contact the subscription provider; don't keep experimenting with query parameters. For not found, check whether the endpoint path has changed. For rate limiting, stop retrying and wait as directed by the server. If the server returns an error, keep the existing list and try the same path again later. Repeated clicks may overwrite the key details in the first log.
Request succeeded but no servers appeared: check the format and filters
A successful response only means the client received content; it doesn't mean the content is an importable configuration. The server may return a sign-in page, network authentication page, plain-text message, or a configuration file for another type of client. Check that the output format specified by the subscription provider matches the client, then ask the provider whether the response should contain an encoded list of links or one share link per line. Don't upload the entire response to an external tool just to identify its format. In most cases, the parsing message in the log and the provider's description of the subscription type are enough.
If the log says the import succeeded but no new servers appear in the current view, switch to that subscription group and clear any search filters in the main list. Then check whether “Filter” is set in “Subscription group settings.” Note its current value and remove only that condition temporarily before retrying. If servers appear, the filter is likely too restrictive rather than the URL being invalid. Restore the filter after confirming it still includes the entries you need. If new servers are listed but the active server still points to an old configuration, select a new entry manually and test it on its own.
04 / Latency and throughput
Slow speeds
First distinguish a slow initial page load from slow sustained transfers or intermittent stalls. They may occur at different points in the connection.
Compare tests under the same conditions
Choose a fixed-size file or a frequently used page that you're entitled to access. Record the network type, test time, and active server. Pause background sync and any large downloads. Keep the device, app, and routing mode the same, and change only the server for two test runs. Don't judge speed by the highest result from a single test. Look for repeatable patterns: a long delay before loading, steady speed once it starts, or a fast start followed by a sharp slowdown. Browser caching can make the second visit look faster. Use a fresh session to compare first visits, and note cached results separately.
If the destination allows direct access, run a separate direct comparison. If direct and proxied traffic are both slow at the same time, check the Wi-Fi signal, activity on other devices, the destination service, and whether the gateway is busy uploading. If only proxy traffic is slow, note when the issue occurs and compare it with another working server. Don't compare throughput between one direct-access site and a different proxied site: they may differ in resource size, cache location, and rate limits. Likewise, a hotspot tested in the morning can't be fairly compared with Wi-Fi tested in the evening to determine which configuration is faster.
Tell connection delays from slow transfers
A latency result in milliseconds doesn't tell you how fast a download will be. A page that takes a long time to load the first time but is smooth afterward may be delayed by DNS resolution, connection setup, the handshake, or the destination preparing its response. Use the browser developer tools Network panel to inspect request timings. Select the main document and distinguish time to first byte from content download time. When using a proxy, the browser may not see DNS queries performed by the client or remote server. So if the panel shows no DNS time, that doesn't rule out a resolution issue. Use client logs from the same time to fill in the gaps.
If a file starts quickly but slows noticeably after a while, compare another server and another destination. If it happens with only one destination, look into rate limits on that site or download source. If it happens with multiple destinations on the same server, check the proxy path, concurrent connections, and device load. If the system monitor shows the core or security scanning process using a lot of CPU throughout the connection, reduce the number of simultaneous requests and see whether load and speed change together. Don't disable system protection based on one low speed test, or change multiplexing, transport, and core all at once in an attempt to speed things up.
Rule out traffic using the wrong route or a network switch
Check whether the whole app is slow or only some of its resources. A web page, video, and images may come from different domains. A routing rule matching the main site doesn't guarantee that later requests use the same outbound route. Check the active routing configuration, then use connection logs to see which outbound route the slow resources use. If switching proxy modes restores loading, identify which domain matched a different rule. Don't leave global proxy mode on as a speed-test conclusion; traffic that should go direct would then take an unnecessary route.
If stalls happen only when switching Wi-Fi networks, waking the device, or switching back from wired to wireless, make a new request and compare it with the old connection that hasn't completed. An existing connection may still be tied to the previous network path; its timeout doesn't mean new connections are also broken. If only video calls or other real-time apps stutter while regular downloads work, check whether the app's transport is covered by the current traffic capture mode. A web download test doesn't tell you how real-time traffic will perform. Once you've confirmed network instability is the cause, improve the connection environment rather than changing the entire server configuration.
05 / DNS resolution
DNS resolution issues
Distinguish the proxy's entry-point domain from the destination domain. Finding a DNS record isn't enough; also confirm which component uses it.
Find out which DNS lookup failed
Note the browser's full error message and compare it with v2rayN's message area at the same time. If the log mentions the server's entry-point domain, the proxy connection may not have been established yet. If it mentions the destination or a domain in a routing rule, determine whether the app, system, or proxy outbound is resolving it. Don't replace the domain in the browser's address bar with its numeric IP to test. Many sites rely on the TLS server name and HTTP host header, and a single IP address can serve multiple sites. Failure to connect by IP doesn't prove there's a DNS problem.
If only one browser has DNS errors, compare it with another browser or a fresh session, then check its “Secure DNS” setting and its own proxy settings. If the app uses its own resolver, system lookup results may be fine while the app still uses a different resolver. If TUN is enabled, DNS queries may also be captured; record the results with it enabled and disabled. Internal domains on an office network are resolved by internal DNS. Sending them to a public resolver isn't a replacement for the existing setup and may expose internal names to an unintended party.
Check the system's DNS path and distinguish records from actual reachability
In Windows PowerShell, run the two commands below to look up the two address record types for a public example domain. To troubleshoot a real issue, replace the example domain locally with the domain that's failing. Don't include a subscription URL's path or parameters in the query. Note your VPN, TUN, and network status before running the commands. These use the system tools to make queries under the current conditions; they don't prove that the browser, proxy core, or destination server uses the same resolver.
Resolve-DnsName -Name example.com -Type A -DnsOnly
Resolve-DnsName -Name example.com -Type AAAA -DnsOnly
If the response says the name doesn't exist, first check the spelling, network scope, and whether that domain should be visible on this network. If the query times out, check whether the current DNS resolver is reachable; that's different from getting an explicit response that the name doesn't exist. Getting only one type of address record can be normal. If both types are returned but the app still times out, the presence of records alone doesn't prove that the corresponding network path works. Note the address family the app actually tried and the error time, then test on the same network. Don't disable IPv6 system-wide as a first step.
Change DNS settings only for the part that handles the failing lookup
Open “DNS settings” in the desktop client and confirm which core the active configuration uses and whether these settings apply to it. Save the current settings before making changes. The entry-point domain must be resolved before the proxy connection is established, so it can't depend on that same connection. For destination lookups after a connection is established, the result depends on the current route and proxy transport. If you use DoH, check that the resolver's own domain can be resolved first, that its connection can be established, and that the system clock is correct. Don't conflate encrypted DNS queries with sending all DNS traffic through the proxy.
If the error comes from one domain-routing rule, start with a small test using a known domain. Check the name the rule matches, rule order, and outbound route, then confirm the change hasn't affected internal domains. For more background, see the DNS split-routing guide. If a term is unclear, check the glossary. After fixing the issue, reopen the app to establish a new connection. If DNS is cached, you can run a new lookup locally, but clearing the system cache doesn't guarantee that the browser or proxy core's own cache is cleared.
06 / Traffic capture and routing
System proxy not working
First check that the system setting was applied, then confirm the app is using it. Routing rules apply only to traffic that has already reached the client.
Check the tray mode against the system's actual settings
Right-click the v2rayN tray icon and open “System proxy.” After selecting “Automatically configure system proxy,” immediately check the active value in your operating system's proxy settings. In Windows, go to “Settings → Network & Internet → Proxy.” On macOS, check “Proxies” in the details for the network service you're using. On Linux, check whether your desktop environment and app read the same proxy settings. The port shown in the system settings should match the local entry provided by v2rayN. If the port changed but the system still shows the old value, reapply the mode and check that the core started correctly on the new port.
“Clear system proxy” removes the system proxy set by this mode; it doesn't disable proxy settings built into every app. “Do not change system proxy” means the client won't actively rewrite the current system settings. It doesn't mean the system is set to direct access or restore values left by another tool to their defaults. If a company device gets its proxy from a management policy or auto-configuration script, note the original settings and test only where permitted. Don't change policies or delete the script. If the system keeps reverting to the same old value after you change the proxy mode, check whether another tool or management policy is rewriting it instead of repeatedly clicking the tray menu.
Test with an app that actually reads the system settings
Choose a browser that is explicitly configured to use the system proxy. Quit it completely, reopen it, and visit a destination you regularly use while checking whether v2rayN receives a new connection. If connection logging isn't enabled in the message area, temporarily turn it on using the client's logging options, then restore the previous level after testing. A page loading successfully doesn't tell you whether it used direct access or a proxy. If the system value is set but no matching request appears in the browser, check for a proxy extension, browser-specific proxy settings, management policies, or a destination on the system bypass list.
If only certain tools are affected, check whether they have their own network settings. Command-line tools may read only environment variables or startup arguments, and some desktop apps read the proxy only at launch rather than tracking system changes. HTTP and SOCKS entries aren't interchangeable, and proxy variables shouldn't point to the remote server address. If manual proxy settings work inside an app, the local entry is usually available; next, find out how the app reads proxy settings instead of replacing the subscription or reinstalling the client.
Once a request reaches the client, check its routing rule
If the logs show an app request but the outbound route differs from what you expected, open “Routing settings” in the client and confirm which configuration is active. You can temporarily compare the outbound result for one test request in “Global” mode and your current routing preset, then switch back to your usual setup. Some destinations may bypass the proxy because of a direct rule. Conversely, matching a proxy rule doesn't guarantee the remote destination is reachable. If no request appears during the test, changing routing rules won't help because the client hasn't received the traffic.
If an app can't be configured to use its own proxy and the system proxy doesn't cover it, consider whether TUN mode and its required permissions are needed. Before enabling it, note the current system proxy state, network, and test app. Verify one traffic capture method at a time so you can tell which one is working. When you're done, undo the method used for the test and check direct access with an app that normally works without a proxy. If a stale proxy points to a closed listener, remove the entry you just added on the system proxy page or restore the original settings you recorded.
07 / Startup and recovery
Client crashes
First determine whether the window is closing, the app is hiding in the tray, or the core process is exiting. Then decide whether to investigate the program, runtime environment, or configuration.
Capture the first error, then check the installation
If no window appears after you double-click the app, check the system tray, menu bar, and process list. Closing the window may only hide the interface, and a second launch may be handled by an existing instance. If the interface is still open but connections fail, the issue may be limited to the core process. If both the interface and core have disappeared, note what happened between launch and exit. On Windows, check the error at that time under “Event Viewer → Windows Logs → Application.” On other desktop platforms, find the corresponding error in the system or client logs. Start with the first relevant entry; don't mistake follow-on shutdown errors for the cause.
If the app exits the first time you launch it after installation, check the system requirements and package on the client download page. Install the Windows desktop and classic WPF editions according to their respective instructions; don't assume they have identical dependencies. On macOS, choose a package for the correct chip architecture. On Linux, check both the package format and system architecture. If the system explicitly reports a missing runtime, install the correct dependency for your installation method. Don't download a missing library from an untrusted site. If the system explicitly blocks the app, check the warning and download source instead of weakening system-wide security settings.
Keep the old data and reproduce the issue with a minimal configuration
If the app worked before and started crashing after an update, back up the current configuration and logs to a location only you can access. The configuration may contain subscription URLs and connection credentials. The installation directory and user configuration directory may be separate, so installing elsewhere doesn't guarantee that the app will use a fresh configuration. Check where the configuration is stored for your platform and installation type, quit the client completely, then temporarily move the directory confirmed to belong to that client. Keep the old directory so you can restore it. Don't wipe the configuration, subscriptions, and logs as part of a reinstall; doing so makes recovery harder and obscures whether the program update or a particular data file triggered the issue.
Launch with a clean configuration, leave TUN and routing rules disabled, and import just one known-working server. Once the interface opens and the core starts, restore subscription groups, routing, and DNS settings one at a time, restarting and testing after each. If importing a particular group causes the app to exit, test importing it separately from automatic updates. The issue may be the data format, a field in one entry, or a rules file. If the app still crashes with a clean configuration, check the runtime environment, directory permissions, or graphical interface error instead of continuing to change subscriptions.
Fix only what the logs point to
If the core process exits while the window remains open, focus on the file, port, or configuration field mentioned in the logs. For a port conflict, first check whether another v2rayN instance or a legitimate program is using it. Close an instance you no longer need, or choose an available port in the client and update any local apps that depend on it. For “Access denied,” check whether the current user can read the core files and write to the relevant configuration directory. If the failure occurs only when TUN is enabled, turn TUN off and test the regular proxy first, then check the required permissions for that feature. Don't avoid the issue by running the entire client with elevated privileges permanently.
If you need to report the issue, include the operating system, chip architecture, installation type listed on the download page, version in use, and the shortest steps that reproduce the problem. Keep the error type and time, but remove full subscription URLs, credentials, and unnecessary device paths. To restore service, clear proxy settings created during testing, close the new instance that caused the issue, and restore the original configuration from backup. Retest the connection with the same server and verify that the system can connect directly after the client exits normally. If the window recovers but the core still fails, continue from the first core error.
08 / Android
Android troubleshooting
First rule out VPN permission issues and conflicts, then check per-app inclusion, network switches, and background behavior after the screen locks.
Tapping Connect does nothing: check the VPN session
The first time v2rayNG starts in VPN mode on Android, the system should prompt you to authorize the connection. If you previously canceled, tap Connect again and check whether the prompt reappears. If it doesn't, open the VPN page in Android Settings—use search to find it—and check whether another app or work profile is using the session. Disconnect conflicting sessions if permitted, then return to v2rayNG. Don't remove configurations managed by your work device policy without permission; ask your administrator whether another VPN can be used.
A VPN icon means only that the system established a VPN session. It doesn't confirm that the server handshake succeeded or that every app uses the same outbound route. Keep v2rayNG in the foreground, select a known-working configuration, and make a new request in a browser included in the VPN. If it still fails, check the log time in the client and follow Server timeouts to verify the entry point and handshake. If the client won't run or installation reports an architecture mismatch, compare the arm64 and universal packages on the Android download page. Choose v2flyNG only if you need the V2Fly core and your configuration calls for it; switching clients won't fix a system VPN permission issue.
Only some apps fail: check the per-app list
In v2rayNG settings, check whether “Per-app proxy” is enabled, then verify the app list and “Bypass mode.” When per-app filtering is enabled, one mode sends only selected apps through the VPN; the other bypasses the selected apps. The list is the same, so choosing the wrong mode reverses the result. Note the old settings and test with just one app. Stop and reconnect the current session, fully quit and reopen the app, then observe a new connection. Don't judge by a page that was already open or a background download that hasn't finished.
Personal and work profile instances of the same app may be different. Confirm that you're testing the instance covered by the settings you changed. Also check “Always-on VPN” and “Block connections without VPN” on the system VPN page. The block option may cut off apps excluded from the VPN; the issue may be a conflict between the bypass list and system policy rather than the server. Don't change system policies without permission. If you manage the device yourself, decide what behavior you need before changing the list or keeping forced VPN routing enabled.
Handle lock-screen disconnects, network switches, and battery drain separately
Start with a short comparison: on the same network and server, confirm that things work in the foreground, then lock the screen briefly. After unlocking, check the VPN and client status before making a new request. If the session ended and this reliably happens after locking, check battery optimization, background usage limits, and manufacturer-specific background settings in the app's system details. Relax the restriction for v2rayNG in one place at a time and repeat the same test. Allowing background activity may use more battery, so keep only the changes that prove necessary. For a more detailed test, see battery optimization and background troubleshooting.
If the session is still active but an old request times out when switching from Wi-Fi to mobile data, wait for the new network connection to finish, then make a new request. If that also fails, reconnect and test the same destination separately on both networks to see whether the new network affects entry-point reachability, DNS, or authentication. If battery drain is the main issue rather than disconnects, compare screen-on and locked-screen behavior over the same period in the system battery usage page. Also check whether the client is repeatedly reconnecting or updating subscriptions, or an app is constantly transferring data. A persistent VPN notification alone doesn't tell you how much battery is being used.
After fixing the issue, test three states: use the test app in the foreground, lock and wake the screen, then switch networks manually. Make a new request in each state and note whether the session is active, apps that need the proxy work, and apps that should connect directly behave as expected. If only one state still fails, keep the steps to reproduce it and the logs from the same time. There's no need to reset the network settings on the whole device.