V2Ray Troubleshooting Guide

No internet: Find where traffic stops

Restore your network before testing the proxy

Quit the client or turn off the proxy, then make sure manual proxy settings are disabled in your system network settings. If regular websites still won’t load, check Wi-Fi sign-in, your gateway, system time, and network connection before changing nodes. Hotel, campus, and public Wi-Fi may require browser sign-in; enabling a proxy can prevent the sign-in page from opening. Once your regular connection works, start the client and test a known-good profile to avoid confusing a network access issue with a proxy failure.

Next, distinguish a running client interface from a core that is actually listening. Open the log panel in v2rayN and look for configuration loading, inbound listeners, and startup errors. If you see an address-in-use error, a configuration parse failure, or the core exiting, the browser hasn’t reached the remote server yet. Check the actual local listening port under Basic Settings or Inbound Settings; labels may vary, so use the current settings and startup logs as your source of truth. Don’t copy a port from a guide or enter the remote server’s port as the system proxy port.

Isolate the issue with an explicit proxy request

The command below assumes an HTTP proxy is listening locally and that its actual port is 10808. On Windows, use curl.exe to avoid a terminal alias; on other desktop systems, use curl. The test URL is only for checking the request path. If only a SOCKS inbound is enabled, use the appropriate SOCKS option instead. Sending an HTTP proxy handshake to a SOCKS port will fail because the protocols don’t match.

curl.exe --proxy http://127.0.0.1:10808 --connect-timeout 10 --max-time 25 -I https://example.com/

If the explicit proxy request succeeds but the browser fails, focus on system proxy settings, browser extensions, and the browser’s own proxy configuration. If the command immediately can’t connect to the local address, check the listening port, core process, and security software rules. If it connects locally and then times out, investigate the node, route, and DNS. The response doesn’t have to be a success status: even a forbidden response may show that the request reached its destination. Check the logs too, to confirm it used the expected outbound.

Use global mode as a short diagnostic test

Temporarily turn off TUN, keep the system proxy enabled, switch the client to global routing, and retry the same URL. If it works, the likely cause is a routing rule or direct connection path, not node authentication. Global routing generally sends traffic that has already reached the core through the proxy outbound; it doesn’t automatically capture every process. If an app still can’t connect in global mode, that alone doesn’t prove the node is unusable. Restore your original mode after testing to avoid routing more traffic than intended.

If only one website fails, compare it with other sites in the same browser and check for certificate, redirect, or sign-in issues. If all proxy requests fail, test a different node for comparison. Don’t start by changing the transport protocol: the protocol, port, path, flow control, and server settings must work together. Changing the protocol on the client alone won’t help if the server has no matching inbound, and may introduce new problems.

Node timeouts: Check transport and authentication separately

Know what the test actually measures

A latency test in the node list doesn’t always make a full proxy request. A TCP test usually checks only whether it can connect to the server port; a real connection test also performs the proxy handshake and requests a test URL. So TCP can succeed while the real connection fails—for example, because of authentication, TLS, the transport path, or the test destination. Likewise, a timeout in the list doesn’t prove that every app is unable to connect. Check the test method and timeout first, then verify with an actual web request.

Test one node at a time and check the logs for the same time period. Testing the whole list repeatedly creates many simultaneous connections, which can trigger remote rate limits, connection limits, or local resource contention—and obscure the original error. Note whether the failure occurs during hostname resolution, connection, TLS handshake, or response reading. If the log only reports a generic timeout, narrow the test to one server and one destination, then temporarily increase log detail. Return to the normal log level when you’re done.

Check the address and port, then the handshake settings

Make sure the server address has no leading or trailing spaces, the port is correct, and the hostname resolves. If every node from the same provider fails, check your account status, server maintenance, and subscription expiration. If only one node fails, suspect its configuration or route. Testing on another network can help distinguish a local network path issue from a remote one, but keep the node and other settings unchanged so you know what made the difference.

For connections using TLS, check the server name, certificate match, transport, and system time. The connection address may differ from the name used for certificate verification; don’t overwrite the server name just because the connection address is a domain. The WebSocket path and Host, and the gRPC service name, must also match the server configuration. These are not arbitrary labels. Unless your provider tells you otherwise, keep the imported settings rather than copying paths or headers from an online example.

REALITY and flow control must match

For VLESS with REALITY, check the public key parameters, short ID, server name, and flow control provided by the server. Field labels may differ between clients, so follow the client’s documentation. Don’t enter the client’s public key parameter as the server’s private key. The xtls-rprx-vision flow is not a universal speed boost; it must be supported by the current core and server setup. For an explanation of how the fields relate, see REALITY and XTLS Vision explained.

Don’t treat allowing insecure certificate verification as a routine fix. It weakens identity verification and won’t help with a wrong port, incorrect REALITY parameters, or an offline server. Correct the system time, server name, and configuration source, and ask your provider whether the endpoint is still active if needed. If an older core reports an unsupported field, first choose a compatible client on the downloads page, then check which core is actually running. Updating the interface doesn’t necessarily update the core’s capabilities.

Subscription issues: Separate fetching, parsing, and applying

Keep existing nodes and check the subscription source

A subscription update has three separate steps: requesting the URL, parsing the response, and saving the results to the right group. Don’t delete your existing nodes as soon as an update fails. They may still work and can help restore your connection or provide a proxy route for the subscription request. First open the subscription group settings, confirm which group is being updated, and check the error log. Similar group names can make it easy to confuse an expired URL with the one currently in use.

Get the full subscription URL from your provider again. Check that copying hasn’t truncated query parameters, added line breaks, or included extra punctuation. Subscription URLs often contain account credentials; don’t paste them into public online converters or include them in public screenshots. If opening the URL in a browser shows a sign-in page, expiration notice, or website error instead of subscription data the client can read, the request reached the site but didn’t return a valid node list. Retrying the update won’t fix that.

Handle the response status and content separately

A request timeout usually calls for checking the network path and DNS. For an unauthorized or forbidden response, check subscription permissions, whether the URL has been reset, and your account status. If the server says requests are too frequent, stop clicking Update and wait before trying again. A successful status doesn’t guarantee valid content: some endpoints return a browser check, sign-in form, or maintenance page, which the client then reports as a parse error. Check both the request result and the response content type.

If the log says the format isn’t recognized, first check that the subscription uses a format supported by your client. A collection of regular share links, encoded link content, and other configuration formats aren’t interchangeable. Don’t judge compatibility by the file extension or delete unfamiliar fields and overwrite the original subscription. Ask the provider for a URL compatible with v2rayN, v2rayNG, or v2flyNG. Import it into a separate test group first; replace the original only after confirming it works.

Check whether the update request uses a direct or proxied connection

Clients often offer options to update through a proxy or without one; the exact location varies by interface. If the subscription URL is unreachable directly, try updating through an active node. But if the current node is down and the subscription requires that node, you’re stuck in a recovery loop. Try a direct update, use an older node that still works, or switch networks instead of repeatedly retrying through a failed node.

If the update succeeds but no nodes appear, check group filters, search terms, list sorting, and the imported node count. A name filter may exclude every node returned by the server. If the update strategy replaces existing content, the node you were using may also be gone. Select a new node, make it active, and run a real connection test. A successful subscription update only confirms that the configuration was fetched; it doesn’t mean every node is online or that the system proxy was enabled.

If only automatic updates fail, note the network status, active node, and proxy mode when the task ran, then compare them with the manual update path. A network that isn’t ready at startup, a device just waking from sleep, or a node switch can all cause a temporary failure. Keep the failure time, not just the last error line, so you can see whether it coincided with a network event. For related settings, see Subscription update failures and automatic refresh intervals.

Slow speeds: Separate handshake delays from sustained transfer

Pinpoint when the slowdown occurs

“Slow” can mean at least three different things: a long wait before a page opens, resources loading one by one, or low sustained download throughput. A slow first response often points to DNS, connection setup, TLS handshake, or retries. Slow downloads are more likely to involve network congestion, server egress, account limits, or local bandwidth. Request the same website twice, then test a large download. Don’t use a single node latency result to judge overall performance; low latency can still come with very low throughput.

Pause other downloads, cloud sync, and system updates before testing, and make sure Wi-Fi and the local network are stable. Use just one client and one traffic-capture method to avoid proxy programs forwarding traffic through one another. Then hold the node, destination, and test window constant while changing one variable at a time. Comparing different websites also changes the server location, cache behavior, and content size, so results describe a particular route—not a universal node ranking.

Compare direct access, system proxy, and TUN

If your regular connection is slow too, troubleshoot the local network first. If only proxy traffic is slow, check the node and route to the remote server. If the system proxy works but TUN is slow, look at traffic capture scope, the DNS path, other virtual adapters, and differences in app protocols. TUN sends traffic from more apps through the client, so background updates and sync may compete for bandwidth. More total traffic in TUN mode doesn’t necessarily mean the core is less efficient; first check which processes were using the network during the test.

If the main page loads quickly but images or video stall, different resource domains may be using different routes. Open the browser’s network panel, identify which domains are slow, then check the client logs to see which outbound each used. A resource domain mistakenly routed directly can make the whole page appear slow. Change only the confirmed problem domains; deleting all routing rules for one website can affect other apps too.

Use care with multiplexing, UDP, and MTU

Multiplexing isn’t a speed boost for every protocol. It can reduce the cost of repeatedly opening connections, but it can also make multiple requests share congestion or failures on one underlying connection. Follow the compatibility requirements of the protocol, flow control, and core. Change only this setting when testing and compare the same scenario; don’t also change concurrency, transport, and DNS. Unless your provider says otherwise, start with the client and node defaults.

Some apps try UDP-based transport first. If the current traffic-capture method or remote server doesn’t support that path, the app may stall while waiting for a failure before falling back. Check the logs and app protocol instead of disabling all UDP. Similarly, investigate path MTU only if some websites stall during loading and the issue occurs only with TUN or a particular network. Record the original value before making small, incremental tests; copying a fixed value from an online guide can cause new compatibility issues.

Finally, test at different times and on different networks. If the same node remains slow across multiple destinations but another node works, give your provider the time window, destination type, and test conditions. If several nodes are slow on the same Wi-Fi network, investigate the network and device first. Don’t keep switching nodes to chase one test result. Repeatable comparisons help distinguish short-lived fluctuations from persistent problems and avoid unnecessary configuration changes.

DNS issues: Check the resolver and query path

Separate system, browser, and core DNS resolution

A device may use the system resolver, browser secure DNS, client core DNS, and TUN DNS interception at the same time. A domain resolving in the browser doesn’t mean the core got the same result; a failed system lookup doesn’t necessarily mean a proxy request will fail. First identify which app, proxy mode, and domain are affected, then check that resolver path. Changing every DNS setting to the same address usually just hides differences between paths.

“Host not found,” DNS timeouts, and failure to connect to the destination address occur at different stages. The first two point to DNS; the last may mean an address was resolved but the connection failed. Use a system tool to check whether the domain returns a record, then make a proxy request to see if the core can reach it. On Windows, use nslookup example.com; on other systems, use an installed DNS lookup tool. The system result is only a baseline—it doesn’t prove the browser or core uses the same answer.

Understand the difference between routing resolution and proxy DNS

The routing domainStrategy controls how domain names and IP addresses are used to match rules; it isn’t a global DNS switch. With IPIfNonMatch, the core first tries domain-based rules, then resolves the domain as needed if none match, and continues with IP rules. It doesn’t resolve every request in advance or guarantee that a specific DNS service will be used for the destination. If the logs show traffic taking the wrong outbound, check rule order, domain conditions, and the resolved address category.

The snippet below is an Xray DNS object for custom configuration reference, not a complete client configuration. Don’t use it to overwrite a whole file generated by the client. It uses explicit query policies to illustrate what the fields do; whether a public resolver is reachable still depends on your network. In a graphical client, change the relevant DNS options in its settings first, then check that the generated configuration matches your intent. If the client rebuilds its configuration, edits to a temporary file usually won’t persist.

{
  "dns": {
    "servers": [
      "1.1.1.1"
    ],
    "queryStrategy": "UseIPv4"
  }
}

Check IPv6, caching, and encrypted DNS bootstrap

Some networks return IPv6 addresses even when the device has no working IPv6 route to the destination, causing intermittent delays. You can temporarily test with IPv4-only queries to isolate the issue, but that doesn’t mean IPv6 should be disabled permanently on every network. Also distinguish DNS query preferences from the outbound connection strategy; they’re separate settings. If the problem persists, check for cached old answers and start a fresh request so an existing connection doesn’t keep using the previous address.

Encrypted DNS also has a bootstrap step: the resolver’s hostname must be resolved first. If that lookup depends on a proxy that hasn’t been established—and the proxy server’s address depends on the same resolver—you can create a loop. Check whether the client supports a separate bootstrap resolver and whether queries go direct or through the proxy. Don’t paste one encrypted DNS address into every field: different fields may expect a server address, URL, rule, or policy, and these aren’t interchangeable.

With TUN virtual address mapping, system tools may show addresses maintained by the client rather than the destination’s actual address. Check the client’s DNS mode before treating an unfamiliar address as tampering. Conversely, an app may have cached a mapped address but fail because its request didn’t go through the corresponding TUN. After switching capture methods, close and reopen the test app and clear its relevant cache if needed, then test the same domain again.

System proxy not working: Check whether the app reads it

The system proxy doesn’t capture every connection

The system proxy is a set of network settings that apps may read, not a rule that automatically redirects every packet. Browsers may follow system settings, command-line tools may read environment variables, and some apps have their own proxy controls. So it’s not unusual for a browser to work while a terminal doesn’t. First use an explicit proxy command to confirm the local listener and remote route work, then decide whether to change the app’s settings or enable TUN for your use case. Don’t mistake app behavior for a core failure.

In v2rayN, make sure the system proxy status isn’t set to Clear or Keep unchanged, then check the operating system’s network proxy settings. On Windows, go to Settings → Network & Internet → Proxy. On macOS, check the proxy options for the current network service. Linux desktop environments usually provide proxy settings under Network. The address should match the local listener, and the port should be the client’s actual inbound port. After switching network adapters, make sure the correct settings are applied to the active network service.

Check for overrides and bypass rules

Browser proxy extensions, automatic proxy scripts, organization policies, and app-level proxy settings can override the system proxy. Temporarily disable relevant extensions in a test browser and check for a separate proxy mode. An automatic proxy script can choose direct or proxied access by address; it doesn’t mean all traffic uses the local port. If only certain domains bypass the proxy, check the bypass list and script rules rather than repeatedly clicking the client’s enable button.

In a terminal, also check environment variables such as HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY. Tools differ in which variables they support and how they prioritize them; an old variable may still point to a closed port. Don’t set permanent environment variables in bulk without understanding how your tools behave. For diagnosis, use the command’s own proxy option first. Once it works, configure the tool as documented and check for rules that bypass local addresses or specific domains.

The SOCKS test below also assumes the actual SOCKS inbound port is 10808. The socks5h option sends the destination hostname to the proxy for resolution, which helps compare it with local DNS; it doesn’t fix system DNS. If the SOCKS test succeeds but regular access fails, return to the app proxy settings or local DNS checks instead of switching remote nodes again.

curl.exe --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 --max-time 25 -I https://example.com/

TUN is for a different kind of traffic capture

If you need to proxy apps that don’t read system proxy settings, check whether TUN is suitable for your platform. TUN relies on a virtual network interface, permissions, and routing settings; it isn’t the same switch as the system proxy. After enabling it, check that the interface was created, routes were added, and DNS is handled as expected, then test the app that failed before. If startup reports a permissions error, changing nodes won’t fix traffic capture. Follow the client’s instructions to grant access first.

Running another VPN, virtual network adapter tool, or TUN setup at the same time can cause route conflicts. During testing, use only one traffic-capture tool and confirm the original routes are restored after quitting it. Don’t bind the server port to every network interface to fix local access: a local proxy usually only needs a loopback address, and widening the listener changes your exposure to the network. If you need to share it on a LAN, configure access controls and the firewall separately rather than mixing that into local troubleshooting.

Client crashes: Separate the interface, core, and system environment

Identify which process exited

If the window is still open but connections fail, the core may not have started. If the whole window disappears, investigate a crash in the interface process. Check client logs, system events, and process status; note whether the exit happened during startup, a node switch, TUN activation, or a subscription update. A working interface doesn’t prove the core is running, and a working core doesn’t prove the system proxy is active. Classifying the failure by when it happens preserves more useful clues than deleting the entire program folder.

Exit the client normally and confirm no background process remains, then back up your user configuration and subscription group details. Store the backup securely: it may contain full subscription URLs and authentication parameters. Don’t upload the whole data directory publicly or place the backup in a website directory. If you plan to reinstall, keep the original copy and test with a fresh configuration. Installing over the old directory can mix old and new files, making it hard to tell whether the problem came from existing settings.

Check the platform, architecture, and file permissions

Confirm the package type on the downloads page. The desktop and classic WPF editions of v2rayN for Windows have different interfaces. On macOS, choose between Apple Silicon and Intel. On Linux, match both the processor architecture and the distribution’s package format. The wrong architecture, missing runtime, or incomplete installation can prevent startup. Check the installer and system error for exact dependencies; don’t download runtime components from untrusted sources based on an old guide.

The client needs write access to its data directory for configuration and logs. A restricted directory, read-only media, or a location repeatedly locked by sync software can cause save failures, settings to revert, or startup errors. Check the actual data directory the client uses, not just the folder containing the executable. Don’t grant every user full access to all files; fix permissions for the relevant user directory. Diagnose administrator-only operations separately from ordinary configuration writes.

For a core startup failure, start with the first error

An address-in-use error usually means another process owns the inbound port or a previous instance didn’t exit. On Windows, use a system resource monitor to find the listening process, or run the command below to check the example port; you may need permission to view process details. Once you identify the conflict, close that program normally or choose a free port in the client, then update the system proxy and app settings too. Don’t terminate an unfamiliar system process or change only the system proxy port while leaving the core inbound unchanged.

netstat -ano | findstr :10808

For a configuration parse error, start with the earliest field or line number in the log; later “connection failed” messages may be consequences. When editing JSON by hand, check commas, quotation marks, and field types. For generated configuration, change the source in the corresponding graphical setting. If GeoIP or GeoSite files are missing, check the path, confirm the files exist, and make sure the client can read them, then use the client’s update option. Copying database files from another app can introduce different labels or formats.

If the issue began after changing custom rules, test with a clean configuration, restore the default routing, and import just one known-good node. If the minimal setup works, restore your original settings one at a time. This helps distinguish configuration issues from installation problems without repeatedly restoring the entire old directory and triggering the crash again. For core compatibility, see Xray-core and V2Fly differences; don’t assume both cores support exactly the same fields.

Android: Check permissions, background activity, and app scope

A VPN icon only confirms that traffic capture is active

v2rayNG and v2flyNG use Android’s VPN service to capture device traffic. The first time you connect, grant permission in the system prompt. If you dismiss it, importing nodes won’t start traffic capture. After the VPN icon appears, check the client logs and make an actual request: the icon only confirms that Android started the service, not that remote authentication, DNS, and routing all work. Test one node first rather than enabling complex per-app rules at the same time.

Android generally allows only one VPN service to be active per user or profile. Another proxy, firewall using a VPN interface, or filtering tool may take over the connection. Quit other services of this type before starting the client you want to test. If Always-on VPN or Block connections without VPN is enabled, confirm that it points to the current client. Otherwise, Android may block network access when the client stops or authorization fails.

If it works with the screen on but disconnects when locked, check background restrictions first

If the connection drops only after the screen locks, check battery management, background activity, and auto-start restrictions. Allow the client to run in the background as needed, and make sure battery saver isn’t stopping its foreground service. Settings names vary widely between devices; open the app info page and look under battery or background management instead of following another brand’s menu. After changing settings, lock the screen and wait before testing again. Note whether the service is still running, its notification remains, and the logs show a reconnect.

Background restrictions and remote session timeouts can happen at the same time. If the client service is still running and only the first request is slow after wake, it may be rebuilding a connection. If the whole service disappears, Android may have stopped it or the app may have exited. Don’t extend every connection timeout indefinitely or use repeated full-list speed tests as a keepalive. Find evidence of a service exit or connection rebuild first, then adjust the relevant setting; otherwise, you may drain the battery without fixing the cause.

Retest per-app routing and network changes separately

If the browser works but one app doesn’t, check the per-app proxy list and whether it means “proxy selected apps only” or “bypass selected apps.” Those modes do the opposite, so selecting the same app has different results. After changing the list, fully close and reopen the app so it creates a new connection. Work profiles, cloned apps, and other user profiles may have separate network boundaries; a VPN in the main profile may not capture their traffic. Check the scope allowed by the system.

If the problem starts after switching from Wi-Fi to mobile data, first confirm the new network works, then stop and restart the client connection. A network switch changes the address and routes, and existing sessions may not survive. If only one network fails, keep the node unchanged and check that network’s DNS, IPv6, and UDP path. If the node hostname resolves differently on the new network, use the logs to investigate rather than blaming the client version outright.

Choose the client based on protocol requirements

On Android, start with v2rayNG; consider v2flyNG when you need a V2Fly core configuration. They aren’t interchangeable just because their names are similar: the core must support the protocols and fields in your subscription. Choose an installer that matches your device’s processor architecture; most recent devices use arm64. If unsure, check the device information or choose a universal package. See Android download options, and check configuration compatibility instead of repeatedly reinstalling over the existing app.

Finish with a minimal test setup: one node, one browser, default routing, and a stable network. Once it works, restore per-app rules, custom DNS, and other options one at a time, testing after each change. If it still fails, note the permission status, network type, core error, and reproduction steps, and remove subscription and authentication details from screenshots. For a fresh check of the import and connection steps, return to the quick-start guide. For terminology, see the glossary before changing settings at different layers based on similar names.