TROUBLESHOOTING / Troubleshooting
v2rayN Troubleshooting Guide
New to v2rayN? Start with the setup steps in the v2rayN configuration guide to install the client, import a subscription, or configure routing. If setup is complete but something is not working, use this page’s contents to find the relevant symptom; there’s no need to reinstall from scratch. The guide helps you build a working configuration; this handbook helps pinpoint where it stops working.
Change one thing at a time while troubleshooting. Note when the issue occurs, which node is selected, the network you’re using, and the proxy mode. Then retest with the same app and destination. If sharing logs, include only errors near the time you reproduced the issue, and remove subscription URLs, user identifiers, and server addresses.
No internet: trace the request from the local entry point to its outbound route
First determine whether the whole device is offline or the proxy path is failing
First, stop the client from taking over network traffic. If virtual network adapter mode is enabled, turn it off in the client. If the client configured a system proxy, use its clear option to undo the change, then verify the result in system settings. Work or school devices may require a specific proxy; restore its original address or auto-configuration script rather than assuming all proxies should be disabled. Try opening a site that should be reachable in your browser, and check the system’s network status. If you’re on a hotel or campus network that requires sign-in, complete its authentication first. If the site still won’t open with traffic takeover disabled, fix the underlying network connection before troubleshooting the proxy.
Once the connection is restored, enable only one traffic takeover method, select the current node, and revisit the same address in the same browser. Don’t enable the virtual adapter, system proxy, and a browser proxy extension at the same time—you won’t know which one handled the request. If a regular website loads but an app fails, try opening the same site in your browser as a comparison. A successful browser test doesn’t guarantee the app uses the system proxy, and an app failure doesn’t prove the entire route is down. If all requests fail after traffic takeover is restored, check that the core started successfully before evaluating nodes. Don’t start by changing protocols or resetting the network.
Check the local listener and application entry point
In v2rayN settings, confirm whether the active listener is HTTP, SOCKS, or mixed, then check the logs for a bind error. Some apps support only one proxy type, so choosing the wrong type can cause failures even when the port is correct. Use the local listener address shown in settings and the port for the current instance; don’t copy values from an old guide. The commands below show how to test a local port. Run them unchanged only if the current port is 10808; otherwise, replace it first. Test with the client running, then, if useful, exit normally and test again to see whether the listener closes with the process.
| Platform | Command | What the result means |
|---|---|---|
| Windows | Test-NetConnection 127.0.0.1 -Port 10808 | In PowerShell, check TcpTestSucceeded. |
| macOS | nc -vz 127.0.0.1 10808 | A successful result only means the local machine accepted a TCP connection. |
| Linux | ss -ltnp 'sport = :10808' | Check for a matching TCP listener; process details may require elevated permissions. |
If the log reports that the port is already in use, check whether another client instance or a core that hasn’t exited is using it. Exit confirmed duplicate instances normally; don’t force-quit system processes you can’t identify. If you need a different port, update any apps where the old port was entered manually, then have v2rayN reapply the system proxy. If the listener is working but requests don’t appear in the core logs, check the app’s proxy entry point first. The current log level may not record access events, so don’t draw a conclusion from that alone. You can temporarily point an app that explicitly supports manual proxy settings at this listener, then restore its original settings after testing.
Verify routing and recovery with a single request
Once you’ve confirmed the request reaches the core, check which outbound route was selected for a failed request. Focus on the actual match, not the policy name shown in the interface. If the destination went direct unexpectedly, check rule order, whether matching uses a domain or an IP address, and whether the running configuration is the one you just edited. When changing routes, adjust a single test rule first, then restore the original policy. Don’t send internal services through a proxy if they’re meant to connect directly. If the expected proxy outbound was selected but the request stalls while connecting to the server or during the handshake, continue with connection timeouts.
Connection timeouts: distinguish DNS, connection, and handshake failures
Identify what kind of test is timing out
First check which test the client is running. Some tests only attempt a TCP connection; others send a real request through the node and wait for the test URL to respond. A successful TCP test doesn’t mean the core completed the protocol handshake, and a failed request may simply mean the test site is unreachable. Don’t use system ping responses to decide whether the proxy works: a remote host can ignore these probes and still accept connections on the relevant port. Test one node on a stable network, then run the same test on a known-working node. Pause batch speed tests while troubleshooting so local connection concurrency and remote rate limits don’t muddy the results.
Record when the first failure occurred, and whether all nodes, one group, or just one node timed out. If all nodes fail at once, check the current network, DNS results for the node domains, the device clock, and whether the core started. If one group fails while another works, check whether they share a server address, transport, or subscription source. If just one node fails, leave the main configuration alone and compare that node’s address, port, and transport settings. After one node recovers, test the others too; separate issues occurring around the same time may not have the same cause.
Use the log stage to guide troubleshooting; changing the timeout isn’t a fix
If the first error says the host can’t be found or DNS timed out, the remote address hasn’t been resolved yet. Check the node domain with the system resolver on the current network, then investigate the core’s own DNS path. If an address was resolved but the connection timed out, check whether the current network can reach the address and port in the subscription. A connection refused is different from a timeout: the former means the connection was explicitly rejected; the latter means no expected response arrived in time. Neither result alone identifies which device caused the problem. If possible, test the same node on another network you’re authorized to use, without changing the server settings at the same time.
If the underlying connection succeeds but the handshake fails, compare the protocol, encryption or security settings, transport type, and any required server name or path against the node provider’s configuration. The display name is just a label and can’t replace these fields. Nodes may use different templates; don’t copy only the address from one and apply it to another. If the log mentions a certificate or time issue, first make sure the system clock is set automatically and confirm the error occurred during that node’s handshake. Don’t disable certificate verification to hide the error. If the settings match the provider’s current configuration, send them the first handshake error with sensitive details removed.
Test the check URL separately from real-world access
If the test times out but the node can load the pages you actually need, check whether the test URL still works on your network. If the client lets you change it, choose a stable HTTPS address you’re authorized to test, and use the same target for both comparisons. Some URLs redirect or require authentication; seeing a page in a browser doesn’t mean the client’s probe will count it as a success. Conversely, a successful speed test only confirms that route to that one target works. If the actual destination still won’t load, check its routing, DNS, and access requirements rather than repeatedly replacing a node that can already handle real requests.
Don’t keep extending the test timeout just to make the warning disappear. A longer observation window may help only when ordinary requests complete reliably, the initial connection is occasionally slow, and DNS and handshake failures have been ruled out. Verify recovery in two steps: first, access the same real destination through the original node; then restore your usual routing and visit an address that should connect directly. If failures happen only after switching networks or waking the device, record how long it takes from the switch to the first request. See whether it recovers once the network is ready before investigating the system proxy or mobile background settings.
Subscription update failures: check the URL, request path, and group
Confirm which subscription you’re updating and how the request is sent
Open v2rayN’s subscription group settings and confirm you’re updating the affected group, not another one with a similar name. Check the URL from beginning to end, including the domain and trailing parameters. Copying from chat or wrapped text can accidentally include explanatory text, spaces, or punctuation. Keep the complete URL supplied by the provider; don’t use the account dashboard URL as the subscription feed. Automatic and manual updates are separate: if an automatic update fails, first check that the group is included in updates, then run a manual update and check the log for that time. Only after a manual update succeeds should you investigate the schedule, catch-up updates after wake, or whether the app runs in the background.
Check whether the update request uses a direct or proxied connection. A page opening in your browser doesn’t prove the client’s subscription request uses the same network settings; check the logs and the client’s current update options. If subscription updates go through a proxy but every old node in that group is down, the update depends on a node that no longer works. First determine whether the current network can reach the subscription URL directly. If a proxy is required, use another working node, then update only the affected group once. Note the original update method and restore it if the test fails. Don’t switch every group to an unverified route.
Distinguish request failures, HTTP errors, and unsupported formats
If the log shows no HTTP status, first check subscription-domain DNS, connectivity, and certificates. If a status code is present, use it to guide the next step. For an authorization error or denial, ask the provider whether the subscription has expired or requires a different dedicated URL. If the address isn’t found, check whether the provider changed the subscription path. If rate-limited, stop retrying and wait as directed by the server or provider. For a server error, save the time and status for support; repeatedly deleting and recreating the group won’t fix a server-side problem. When sharing logs, include only the failing stage and status. Treat the full URL, including its parameters, as a credential.
A successful response doesn’t necessarily mean the subscription imported. The URL may return an account login page, an error message, an empty response, or a format the client doesn’t support. If parsing fails, check whether the provider offers a separate subscription URL for this client; don’t append format parameters at random. Even if the URL shows content in a browser where you’re signed in, the client may not share that login session. Don’t submit subscription contents to an untrusted online converter. If you need help from the provider, describe the response type, time of the error, and client name. Check the client’s response summary where possible; don’t save the full response body to a public log.
Check what changed in the list after a successful update
If the log says the update completed but the list looks unchanged, check the selected group, search field, and update target, then compare the settings of a known node. Don’t rely on aliases or the node count alone. Some entries may be skipped because they’re invalid or use an unsupported protocol; check which entries were skipped and the import message rather than assuming the whole group failed. Conversely, a higher count doesn’t mean the new configuration works. Select a recently updated node from that group and make a real request. If you maintain entries manually, keep them separate from subscription-generated entries so later server updates aren’t mistaken for a failure to save local changes.
Slow speeds: use controlled comparisons to find the bottleneck
Pinpoint which part of the request is slow
Determine whether the problem is a long wait before the page opens, consistently slow transfers after it opens, or periodic stalls during a transfer. A long initial wait followed by steady data transfer points to DNS, connection setup, or the handshake. If the request starts quickly but repeatedly stalls during a download, investigate throughput, packet loss, destination limits, or network changes. A single node’s latency doesn’t predict file download speed: routes, server load, and response times vary by destination. A webpage may load resources from several domains, so the main page starting to respond doesn’t mean every request is working. Pick an action that reliably reproduces the issue.
Compare results using the same app and destination at roughly the same time. Stay on the current network and test once with the original route, then change only to a known-working node and test again. After that, try the same node on another network. You can also test a public resource directly if it’s safe and expected to be reachable; don’t include a failed direct connection in the speed comparison if the destination normally requires a proxy. Pause background tasks that use bandwidth so the tests don’t take different cache paths. Use the same public file size, record the time to first response and the transfer time, and repeat a few times to check consistency rather than relying on a single peak result.
Use the scope of the slowdown to narrow it down to routing, the network path, or the destination
If only one site or file type is slow, first check whether it’s using the expected outbound route. A page may load static assets from different domains; if the main document uses the proxy but its assets connect directly, the page frame may appear while its content stalls. Use the browser’s network panel to identify the slow request, then compare it with the core logs. Keep routing tests narrowly scoped to traffic you’ve confirmed is affected. If one service is slow while other common destinations work, check whether it limits speeds based on sessions, accounts, or connections rather than replacing your entire routing setup.
If all nodes are slow and direct connections are slow too, check local Wi-Fi signal strength, network congestion, and traffic from other devices first. If slowdowns happen at a particular time of day, repeat the comparison at the same time and see whether the issue follows the network or the same service. If one node remains slow across multiple networks while others work, switch to a verified node and share the comparison with the provider. Check upload and download speeds separately; normal browsing can coexist with slow uploads. Background sync saturating the upload can also delay interactive requests. If pausing it helps, adjust its concurrency or schedule rather than changing proxy protocols.
Change advanced settings only when the evidence points to them
Don’t start by changing system-wide network adapter settings or blindly increasing the number of connections. Investigate the virtual adapter path, adapter conflicts, or packet size limits only if sustained transfers repeatedly fail in virtual adapter mode on the same network, node, and destination, while the app works normally through the local proxy. First exit other apps that may also be taking over traffic, re-establish the connection, and test again. If the client lets you adjust related settings, note the original values and change one at a time. Revert any change that only improves one speed test or causes problems in other apps. Without a repeatable test case, don’t apply experimental settings across all networks.
After making a change, retest the original scenario instead of substituting an easier speed test. If the issue occurred during a long download, run the same kind of download until it reaches the point where it used to stall. If it occurred while opening a page, make a fresh request to the same domain and confirm the initial wait is shorter. Record the one change that helped and the network where it applies. If the old network still fails but another network works, document both results separately rather than claiming the client is fixed under different network conditions.
DNS issues: distinguish node domains from destination domains
Identify which component is making the DNS request
First record whether DNS failed for the node’s server domain or the destination domain. The node domain may need to be resolved before the proxy connection is established. The destination domain may be resolved by the system, browser, local core, or remote server, depending on the proxy entry point and configuration. A successful system lookup only proves that the resolver used by that command worked; the browser’s secure DNS or the core may use a different resolver. A destination address in the core log doesn’t necessarily mean the device resolved it locally; the app may have supplied an IP address. When results differ, identify the component making the request before changing settings at the relevant layer.
Compare how different apps handle the same failing domain, and record the returned address type, error, and time. If multiple apps can’t resolve it, check the current network’s system DNS settings and the spelling of the domain. If only one browser fails, check whether it uses its own secure DNS and whether the domain resolves only on the current network. If an app sends the domain to the proxy for resolution, a result from a local command may not reflect what happens during access. Don’t replace an HTTPS URL with its IP address to test DNS; that changes certificate validation, virtual hosting, and routing.
Cross-check lookup results with a fresh request
The commands below check how the default resolver in common desktop environments responds to a public example domain. To troubleshoot an actual issue, replace example.org with a failing domain you’re authorized to test, and check IPv4 and IPv6 records separately. A domain having only one record type doesn’t mean DNS is broken. If both types are returned but the app still can’t connect, check which address it actually selected and whether that address is reachable. A timeout, a nonexistent domain, and a missing requested record are different results; don’t treat them all as a failed DNS server. Internal domains should only be queried through an authorized internal resolver.
nslookup -type=A example.org
nslookup -type=AAAA example.org
When comparing results before and after switching networks, don’t rely solely on whether an old tab reloads. Existing connections may keep using an old address, and apps, the system, or the resolver may cache earlier successes or failures. After changing settings, close the relevant page or app, start a fresh request, and check the logs. Don’t clear every cache at once, or you won’t know which one affected the result. If DNS works again but the destination still won’t open, check the address selected for the request and its route. If a rule depends on the domain but the inbound request contains only an IP address, check whether the information required for matching is available.
Understand resolver startup dependencies and rule scope
If the core uses a separate DNS service, check whether connecting to that service requires resolving its address first or depends on a proxy outbound that isn’t connected yet. If the node domain needs an address before the connection can start, but the DNS service is reachable only through that node, the setup has a dependency loop. Don’t route all queries through a connection that isn’t up yet. Keep a working bootstrap resolution path, then handle targets that need separate DNS by scope. On managed networks, first confirm the rules for internal domains, search suffixes, and private address resolution. After a change, test node domains, ordinary public domains, and required internal names separately so you don’t fix only one category.
Before editing the core configuration, confirm that each field belongs to the core currently in use; don’t paste another core’s configuration structure into it. Domain matching in routing rules, domain matching in DNS settings, and restrictions on returned addresses apply at different stages. If a rule doesn’t work, first check whether the client-generated or manual configuration is loaded, then look for unknown fields or data-file read errors in the logs. For a field-by-field explanation, see V2Ray DNS configuration explained. For troubleshooting, rely on the actual request and the response from the resolver in use.
System proxy not working: check its scope and stale settings
First confirm whether the app uses the system proxy
The system proxy is an entry point that apps can use; it doesn’t capture all device traffic. Check whether the affected app uses the system proxy, its own proxy settings, or proxy environment variables provided by its runtime. Compare it with a browser known to use system settings, then fully quit and reopen the affected app. Some apps read proxy settings only at startup; closing a window may leave them running in the tray, or they may run under an account environment different from the desktop. If the browser works but the affected app never reaches the core, don’t start by changing routing rules. Find where that app reads proxy settings and determine whether it needs manual configuration.
After selecting automatic configuration in the client, check the address, port, and exceptions actually set in the system—not just the tray menu. Choosing not to change the system proxy may leave existing values in place; it doesn’t automatically restore a direct connection. On a device where the proxy was set manually, record its original exceptions and auto-configuration URL too. When entering the local listener in an app, choose HTTP or SOCKS according to what the app supports; an open port alone doesn’t mean the proxy type is compatible. For an initial test, use a public domain that isn’t in the exceptions list, then compare it with an internal site that should be excluded. Confirm that both proxying and exclusions work as expected.
Check where the setting takes effect on each platform
| Platform | Check first | Common differences |
|---|---|---|
| Windows | Settings → Network & Internet → Proxy | The desktop user’s proxy settings differ from the WinHTTP settings used by some services. |
| macOS | Details for the active network service → Proxy | Wi-Fi and Ethernet services can have separate saved settings. |
| Linux | Desktop session network proxy and the app’s own proxy options | Desktop apps, terminals, and system services can have different startup environments. |
On Windows, distinguish the current user’s system proxy from WinHTTP, which some services use. If a desktop browser works but a background service fails, check which network interface and account the service uses; don’t copy the desktop proxy settings to the entire system. On macOS, check the active network service and recheck after switching between Ethernet and Wi-Fi; don’t rely on a service configured earlier. On Linux, pay close attention to how the app starts: a process launched from a terminal may receive different environment variables than one launched from the desktop. Check the app’s documentation to confirm which settings it reads before changing anything.
If proxy values keep changing back in system settings, check for management policies, another proxy app, or a browser extension that also controls them. Exit any duplicate traffic takeover app you can identify, preserve managed settings required by your device administrator, and then run automatic configuration once on its own. To test whether the system proxy’s scope is the issue, don’t enable virtual adapter mode at the same time. Before switching takeover methods, disable the current one and confirm the system has returned to its baseline. Whether a virtual adapter can capture an app also depends on routing, exclusions, and permissions; it isn’t a shortcut for fixing an app’s proxy settings.
Clear stale settings after exit and test again
If pages stop loading after you exit the client, check whether the system or an app still points to the local listener that was just closed. If you can launch the client again, use its clear option first, then verify the system settings. If it won’t launch, restore the proxy configuration you recorded before troubleshooting. Some apps save proxy addresses separately, so restore those manual settings too. If your device doesn’t normally use a proxy, make sure nothing still points to an old local port. If you rely on a work or school proxy, restore the configuration provided by your organization rather than clearing every proxy field. Restart affected apps after making changes so they don’t keep using an old connection.
Finish with two checks: with the client running, confirm that expected requests use the correct entry point; after a normal client exit, confirm that resources meant to connect directly are still reachable. If the issue returns after waking from sleep or switching networks, record the active network service, system proxy values, and local listener status before and after. Identify which changed first. If the status icon doesn’t match the actual connection, trust the system settings and request records. If only one app is affected, check its settings again rather than resetting the whole network.
Client crashes: distinguish the app interface from the core
Identify when the app exits
First determine whether the interface never appears after you click the icon, appears and closes immediately, or stays open while the core exits during startup. For the first two cases, check system app events and the client startup log; for the last, start with the core log. Note when the startup error appears and keep the first error near that launch. Later errors in a chain often result from the first failure. If the crash happens when opening a particular page, loading a specific group, or selecting a particular node, record the action and whether it happens every time. Don’t keep restarting the app; each new attempt can make the most useful first log entry harder to find.
If no interface appears, the app may not have crashed. First check whether it’s minimized to the tray, whether its process is still running, or whether you launched a second instance while another is already open. If the process disappears shortly after launch, check whether the system blocked it or whether the error mentions runtime dependencies, processor architecture, the working directory, or file permissions. If you launched it from an app launcher or desktop shortcut, confirm the shortcut still points to the current installation. For security policies or device management restrictions, follow your device’s rules and ask an administrator; don’t test by disabling security features. If the client won’t start and a stale proxy remains, restore the system’s previous proxy settings before continuing.
Use the first error to check the installation, port, and configuration
If the error points to architecture or startup dependencies, check that the package matches your system. For desktop use, v2rayN is the recommended choice; the download center separates desktop editions, classic interface, processor architecture, and package formats. On Windows, don’t mix program files from the two interface editions. On macOS, check Apple Silicon versus Intel. On Linux, check both the distribution’s package format and processor architecture. If multiple client copies are installed, launch the one from the expected location to avoid loading files from an older directory. If the error says the data directory isn’t writable, check the current account and file ownership; don’t rely on elevated permissions long term to hide a permissions problem.
If the interface runs but the core exits, identify whether it failed while reading files, validating configuration, binding a port, or initializing the network. For a bind failure, follow the local listener steps. For a read failure, check the path, whether the file exists, and whether the current account can access it. If a manual configuration fails with a field error, confirm which core is selected, then check the brackets, quotation marks, field capitalization, and duplicate sections near the reported line. The snippet below shows the top-level log field in an Xray configuration for comparison with an existing file; it isn’t a standalone configuration you can connect with. Don’t add a second top-level field with the same name when merging it.
{
"log": {
"loglevel": "warning"
}
}
Reproduce with a clean configuration, then restore settings in batches
If you suspect corrupted settings, fully exit the client, back up its configuration data locally, and note where the files are. Prefer a temporary configuration or separate-instance test supported by the client. If neither is available, confirm the data directory belongs only to this client, then move the old directory aside temporarily so the app can initialize a fresh one. Don’t delete data without a backup or move files from other apps at the same time. If the clean configuration opens, restore one category of settings at a time: test a single node first, then restore subscriptions, routing, and startup preferences. If the app exits again after restoring a batch, roll that batch back and narrow down the cause; there’s no need to clear settings that work.
If the app still exits with a clean configuration, note the system environment, package type, steps that trigger the issue, and first error. Then decide whether you need a package that matches your platform or an administrator to check permissions. After fixing the issue, run the app under a regular account, exit normally, restart it, and repeat the action that previously triggered the crash. To see how inbound, outbound, and routing fields refer to one another, read V2Ray configuration file structure. Don’t replace a working configuration with example snippets from a guide.
Android: permissions, app scope, and background connections
First confirm Android allows the VPN connection
On Android, v2rayNG is the first choice; for configurations that require the V2Fly core, choose v2flyNG if it suits your needs. The first time you connect, check whether Android prompts you to authorize the VPN. If you deny or dismiss the request, the client may still show a selected node even though Android hasn’t established a connection. Start the connection again in the client and check whether Android’s VPN settings show the active app. If another app already controls the VPN for the same user or profile, check whether it can be paused temporarily. On managed devices, don’t disable an enforced connection policy; ask your administrator what’s permitted. The client’s running status alone doesn’t confirm the system connection is active.
If the same subscription works on desktop but not on your phone, connect both to the same Wi-Fi network and test the same node and public URL. Confirm the phone has selected the updated entry and that it supports the node’s protocol and transport settings. Desktop success may depend on a different core, route, or update method; it doesn’t automatically mean the mobile package is faulty. If the app won’t open, use the Android download guide to check the processor architecture. If it launches but requests fail, start with the connection logs instead of repeatedly reinstalling it.
Check traffic scope when only certain apps fail
If a browser works but a particular app fails, check whether per-app proxying is enabled. Confirm whether the current mode includes only selected apps or excludes them; the same list has different effects in each mode. Some devices have separate copies of apps in personal and work profiles, and selecting one doesn’t select the other. If you change the list, note the original exceptions and, as permitted by your device policy, change only the app you’re testing. Save, reconnect as required by the client, and test the app. Don’t add unrelated apps to the test; that could change where their sync and authentication traffic goes.
If all apps lose connectivity when the proxy is enabled, first confirm the current network can reach the test site, then check the client logs for node DNS, connection, or handshake errors. Android’s Private DNS setting may interact with the client’s DNS strategy, or affect only some apps because their traffic takes different paths. Note the current setting and whether it’s controlled by a device policy; don’t treat disabling Private DNS as a universal fix. If failures happen only when switching between Wi-Fi and mobile data, wait until the new network is actually available before reconnecting. Keep logs from before and after the switch to see whether the connection wasn’t re-established or the node failed on the new network.
Retest after screen lock and network changes
If the connection is stable with the screen on but drops after the phone has been locked for a while, check whether Android still shows the VPN as connected, whether the client notification remains, and whether the connection recovers after unlocking without manual action. A missing notification may be due to notification permissions, so check the system connection status too. If the VPN is still connected but requests fail, investigate network sleep, a network switch, or a failed node. If the VPN connection itself disappears, check the app’s background restrictions. If your system allows it, adjust only this app’s battery or background permissions, then retest using the same lock duration that triggered the issue. There’s no need to disable power saving for the whole device.
If Android has Always-on VPN and Block connections without VPN enabled, the device may appear completely offline while the connection is being re-established. First check that the app assigned by the system is the client you’re using. Before switching clients, confirm whether this policy can be changed. Test screen lock and network switching separately rather than in the same run. After the issue is resolved, keep the background permissions you need and undo temporary test settings. If you’re still deciding which client to use, start with the client comparison. For quick answers about installation and everyday settings, see the FAQ.