V2Ray Clients
Troubleshooting

No Internet Access: Separate Network Issues from Proxy Issues

Stop the proxy and check that your regular connection works

v2rayN → Clear the system proxy and turn off TUN mode; v2rayNG → Disconnect. First, try opening a site you can normally access without a proxy and check whether the network requires a sign-in page. Public Wi-Fi may show as connected before you complete its login. A client starting successfully doesn't mean your device has internet access. If you still can't browse with the client off, check the Wi-Fi signal, router connection, and system network settings. Don't change node settings yet.

Switch to another network and test again without changing the node or client settings. For example, switch from Wi-Fi to mobile data and see whether direct access works. If only one network fails, focus on its sign-in requirements, DNS, and access policies. If all networks fail, check the device itself. Pause other apps that route traffic during testing, especially other VPNs, network accelerators, and security software with proxy features. They can conflict over routing.

Check each layer: core startup, node connection, and traffic routing

Restart the client and check the logs for a core process exit, configuration error, or port conflict. A running interface doesn't guarantee the core is still running. Once the core stays up, run a real connection test on the active node, then try accessing a site in your browser. If the connection test fails, see Node Timeout. If it passes but the browser still can't connect, check the system proxy, app proxy settings, and DNS. Don't switch protocols right away.

On desktop, temporarily turn off TUN and use only the automatic system proxy to reduce the number of variables. If the browser works this way but fails with TUN on, check virtual adapter creation, permissions, and route conflicts. Conversely, if TUN works but the system proxy doesn't, check whether the app reads the system proxy and whether the system address and port still point to the current client. These modes route traffic at different layers, so one working doesn't prove the other is configured correctly.

Use a small number of tests to distinguish general issues from site-specific ones

Test two different sites and check other apps at the same time. If only one site fails, the service may be down, your account may be restricted, the certificate may be invalid, or a routing rule may be matching unexpectedly. If the browser shows a certificate warning, check your system date and time zone first. Don't disable certificate verification as a routine fix. If only one app fails, check its own proxy, DNS, and cache settings. If every app fails, the issue is more likely with the shared connection or system-level routing.

Once internet access is restored, exit the client and confirm that it clears the system proxy correctly. A proxy address left behind after an unexpected shutdown can make it look as if the internet is still down after the next reboot. Don't reset all network settings right away. Save the logs around the time of the issue and keep your original settings; broaden the scope only if the evidence points to a system-level cause. For basic checks, compare your findings with the first connection checklist.

Node Timeout: Check Connectivity, Handshake, and Test Target

First, find out where the timeout occurs

Node list → Run a real connection test, then check the logs for errors at the same time. A connection timeout means a step didn't finish within the allowed time; it doesn't necessarily mean the server is permanently down. DNS lookup failure, a failed connection to the server port, a handshake error, or an unresponsive test target after the proxy connects can all cause a failed test. Check the stage and destination in the error before deciding what to do next. A single result in the node list can mask very different causes.

If the log stops at the server address, check whether the subscription was just updated, whether this node is still selected, and whether its hostname resolves. Compare it with another node in the same group, then try a different network. If one node fails but others work, suspect that node's configuration or server. If every node in one group fails but other groups work, check that group's service status. If all groups fail, check the device network, system time, and client core startup instead of changing every node at once.

A successful port connection doesn't mean the protocol handshake succeeded

A reachable port only proves that a service accepted the connection. It doesn't confirm that the user ID, transport, and encryption settings match. For handshake errors, check the protocol, server port, transport type, TLS setting, server name, and path one by one. With transports such as WebSocket, the path and Host field must also match the server. For REALITY, verify the public key, short ID, and server name too—don't guess. The safest fix is to reimport the original configuration from a trusted source, not try random values.

Go to System Settings → Date & Time, enable automatic time, and try again. A clock that's significantly off can affect certificate validity checks, and some protocol authentication also depends on time. If the certificate hostname doesn't match, check the server name against the provider's instructions. Don't allow insecure connections as a workaround. If the configuration came from an old clipboard entry, check for stray line breaks, full-width characters, or an outdated port. Back up the node before editing so you can compare it with a fresh import.

Check for differences between the test target and real-world access

A real connection test usually sends a request through the proxy to a specific target. If that target is temporarily unreachable, changes how it responds, or gets routed through a different exit, the test may report a failure. Check the test URL in the client settings and make sure it's still valid, then use your browser to access another site through the same node. Don't keep lowering the timeout just to get a passing result, and don't treat access to the test target as proof that every internet service is available.

For more detail, you can check a TCP port in Windows PowerShell. The command below checks whether anything is listening on an example port on your own machine. To check a remote server, use its actual address and port. A successful result still doesn't prove proxy authentication works. On macOS and Linux, you can use built-in network tools for similar checks. You don't need to install a full toolkit for one troubleshooting session; client logs usually show enough to identify the stage that failed.

Test-NetConnection -ComputerName 127.0.0.1 -Port 10808

If the same node works on another device, compare whether both devices have the latest subscription, support the same core features, and have any manually overridden fields. Similar-looking interfaces in v2rayN, v2rayNG, and v2flyNG don't mean every configuration extension is interchangeable. Keep the provider's original settings and report the specific handshake error and time of failure. That's more useful than simply saying “timeout.” Don't share logs publicly if they contain user IDs, subscription links, or full server details.

Subscription Update Failed: Separate Download Errors from Import Errors

Start with the subscription URL and update method

v2rayN → Subscription Groups → Subscription Group Settings; v2rayNG → Subscription Group Settings. Check that the full URL is present. Common copy-and-paste mistakes include selecting only part of the link, copying its description too, or leaving spaces at either end. Subscription URLs may contain personal access credentials, so inspect them only on your device—don't paste them into public converter tools. If the provider generated a new URL, the old one may have expired; copy the current link instead.

First, check whether the update failed because of a timeout, DNS lookup, certificate issue, or server access denial. For a timeout, check your network. For a DNS error, see the DNS section. For a certificate issue, check your system time and the certificate details. An access denial or missing resource usually means you need to check your account, whether the URL has expired, or whether the provider changed the endpoint. Repeatedly clicking Update won't tell you anything new about account access.

Test direct updates and proxy-routed updates separately

Subscription updates need an internet connection too. If your current node is down and updates are set to use the proxy, you can end up in a loop: you need a working node to download new nodes. First, try the client's option to update without a proxy. If that fails but you have another working connection, keep it connected and try updating through the proxy. Menu labels vary between builds; the important thing is to know which route the request actually takes. Don't just toggle a setting without checking the logs.

Even when an update reports success, confirm that it returned node data. Some networks redirect subscription requests to a Wi-Fi sign-in page; some services return an account-expiration notice or regular web page. The download may complete, but the parser can't turn that content into nodes. If the client provides update logs, look for messages such as unsupported format, no valid servers, or empty content. You can inspect the response in a local browser, but don't save or share a full-page screenshot containing credentials.

Keep the original group and test the format with a small import

Don't delete the entire group before updating. Keep any working configurations and, if needed, export them to a protected folder you control. Then create a test group and import the same subscription. If the new group imports successfully but the old one doesn't, check the old group's filters, automatic sorting, aliases, and override options. If neither group can import it, confirm that the provider's format is supported by your client. A configuration file, a single share link, and an aggregated subscription are different input types; the URL alone doesn't tell you which one you have.

Subscription updates can affect generated configuration. Manual changes made directly to subscription nodes may be overwritten the next time the subscription updates. For changes you need to keep, check whether the client supports separate overrides or custom configuration. After an update, make sure the active node still exists, select a valid node, and run a real connection test. A change in node count isn't necessarily an error: providers may add or remove entries as expected. Judge by whether the configuration is valid and the connection works.

If only a new protocol combination won't import, check the client downloads page to confirm which client you need, then review its configuration support. On Android, start with v2rayNG; consider v2flyNG only when you specifically need a compatible core configuration. Different core families support different extensions, so changing the app name won't make them compatible. For common import options and subscription basics, see the FAQ to avoid mistaking a format issue for a complete node outage.

Slow Speeds: Separate Slow First Loads from Slow Transfers

Pinpoint what feels slow before you choose a test

A page that takes a long time to open but loads quickly afterward is a different issue from a large file that downloads slowly the whole time. The first case usually involves DNS lookup, connection setup, or the handshake. The second is more likely related to bandwidth, packet loss, server load, or traffic policies. First, stop background downloads, cloud sync, and video playback. Test one node, one app, and the same resource each time. If Wi-Fi is unstable, move closer to the access point; on desktop, try a wired connection if available. This helps separate local wireless retransmissions from proxy performance.

Use a resource that works over your regular connection as a baseline, then access it through the proxy. If the resource itself limits speed, it can't tell you how much capacity the exit has. Different sites may use different content delivery endpoints, so even the same download URL can take a different route. One test only describes that connection at that moment. A real connection test's completion time isn't download bandwidth: it mainly measures the wait to establish a request, not congestion or stability during a long transfer.

Keep variables fixed while comparing nodes, networks, and times

First, switch nodes on the same network. Then keep the node and switch networks. Finally, retest at a different time. This helps isolate the server exit, local network, and peak-hour load. If only one node is slow, check its service status. If every node is slow on one Wi-Fi network, check the signal, router load, and network provider. If all devices are slow when accessing the same destination, consider the destination site or a shared exit. Record what you observe in each test; you don't need to saturate the connection for a long time.

Routing rules can also affect speed. A resource that should be accessible directly may be sent through a distant proxy exit. On other pages, the main content might connect directly while images and API requests go through the proxy, making parts of the page appear stuck. Check the routing mode, rule order, and destinations shown in the logs. You can temporarily switch to a simpler routing setup for comparison, then restore your original settings. Don't use permanent global proxy mode to hide a rule error, or assume that one faster site means the same mode is right for every app.

Adjust TUN and MTU only when the evidence points to traffic routing

If browser transfers work with TUN off but large downloads stall with it on, check the virtual adapter, other VPNs, and MTU. An MTU that's too large can cause fragmentation or retransmissions on some routes, but it's not the cause of every slow connection. Note the original value, make a small adjustment, and retest the same resource. Revert if the improvement isn't consistent. Don't change MTU, DNS, transport settings, and the core all at once; even if things improve, you won't know which change helped.

Apps for video, audio, and gaming may also use UDP or QUIC. A route that handles web traffic over TCP correctly may not forward UDP traffic the same way. If only these apps lag, check whether the node and client routing mode cover the traffic they use, and look for apps falling back to another transport. Disabling an experimental browser feature can be useful as a short-term comparison, but it isn't a universal optimization. Don't change unrelated system settings to chase a single speed test result.

Check device resource usage too. Large rule sets, frequent logging, and many concurrent connections can make the CPU or storage a bottleneck on lower-powered devices. Stop repeated speed tests, turn off unnecessary debug-level logging, and observe normal use. Don't disable system protection to improve speed. If the proxy is shared, check whether other devices are using the same exit. See the LAN sharing setup guide for listening and access settings. If the cause is server congestion, local client tweaks usually won't fix it. Try another available exit or report the time and test conditions to the provider.

DNS Issues: Find Out What's Resolving the Domain and Where

A domain lookup failure doesn't mean the proxy server is unavailable

If the logs show a lookup failure, unknown host, or repeated DNS wait, first find out whether the failed name belongs to the proxy server or the destination you're trying to reach. A proxy server hostname can fail before the proxy connection starts. If it can only be resolved through a proxy that isn't connected yet, you may have a dependency loop. For a destination hostname, check the client DNS settings, routing policy, and how the target app resolves names. A browser spinning on a page doesn't tell you whether the local or remote resolver is at fault.

On Windows, run the command below in a terminal to see whether the system resolver returns a result. It uses a public documentation domain to check basic system DNS behavior. A returned address doesn't guarantee the site is accessible, and it doesn't mean the proxy core uses the same resolution path. If the system lookup succeeds but the client logs still show DNS errors, check the DNS server addresses in the core configuration, the outbound used for lookups, and domain policies. Repeatedly clearing browser history won't help identify the cause.

nslookup example.com

Check system, browser, and client settings

Go to System Network Settings → DNS and note whether DNS is automatic or manually configured. Then check whether the browser uses secure DNS and whether the client has its own DNS settings. These can coexist, but the same domain may resolve differently, and some settings may bypass your intended routing rules. During troubleshooting, choose one clear resolution path and temporarily turn off unnecessary overrides. Restore them one by one after testing. On corporate or campus networks, preserve access to any internal domains they need to resolve.

Encrypted DNS also needs a connection to the DNS service itself. If its address is a hostname, that name must be resolved first. If the routing rules send that request through a proxy that hasn't connected yet, the same dependency loop can occur. Follow the client documentation to configure a reachable bootstrap resolver and outbound route rather than piling on more DNS services. Adding more servers doesn't always improve reliability; parallel lookups and routing can make results harder to explain.

Understand how DNS lookups relate to routing

The snippet below shows DNS and routing fields in a core configuration to explain how they relate; it is not a complete file you can import into a client. It shows a list of DNS servers and an on-demand resolution policy. A working setup still needs a complete inbound, outbound, and other required configuration. In a graphical client, change the corresponding client settings where possible. Editing an auto-generated file directly may not stick after a restart or node switch. Check which fields each core supports.

{
  "dns": {
    "servers": [
      "1.1.1.1",
      "8.8.8.8"
    ]
  },
  "routing": {
    "domainStrategy": "IPIfNonMatch"
  }
}

A domain-based rule may choose an outbound route before DNS resolution. Rules based on IP ranges may require an address first. Check resolution results, rule order, and the connection destination together. If direct access to a returned IP fails, that doesn't prove DNS is broken: many sites require the correct hostname and TLS server name, so entering an IP isn't an equivalent request. Address-level tests are useful only when you understand how the destination service works.

After changing DNS settings, old results may remain in the system, browser, or app cache. On Windows, once you've confirmed the new settings are active, run the command below, restart the affected app, and make a fresh request. Clearing the cache only triggers a new lookup; it can't fix an unreachable DNS server. If a domain fails on only one network, compare that network's DNS and sign-in status. If it fails only with TUN on, check DNS routing, virtual adapter routes, and conflicts with other network tools.

ipconfig /flushdns

System Proxy Not Working: Check the App and Listening Address

First, make sure the client and system point to the same port

v2rayN → Set system proxy, then open the proxy page in System Network Settings. Check that the address is the local loopback address and the port matches the one the client is actually listening on. A common local port is 10808, but use your current settings instead of forcing a number from a guide. A core that isn't running, a port used by another app, or an old port saved in system settings can all make it look like the proxy is on when access still fails. Confirm the local entry point works before troubleshooting the remote node.

Also check which proxy protocol the listening endpoint accepts in the client settings. If an app is configured for an HTTP proxy but the endpoint accepts only SOCKS, or vice versa, the connection may fail immediately or return unexpected content. Some builds provide a mixed endpoint that accepts multiple proxy protocols; others use separate ports. Don't infer the protocol from the port number. A LAN listener is also different from a loopback listener. For local use, you usually don't need to allow connections from the LAN.

The system proxy only affects apps that use it

A browser may use the system proxy, its own proxy setting, or an extension. Pause proxy extensions, check that the browser is set to use the system configuration, and open a new page while watching the logs. If the client doesn't see the request, the traffic may not be reaching the local endpoint at all. Command-line tools, games, and some desktop apps don't necessarily use the system proxy. Check each app's network settings; a working browser doesn't prove that every app will use the client.

Compare an explicit proxy request with a regular request. The command below assumes the local 10808 endpoint accepts HTTP proxy traffic and the core and active node are running. If you use a different port or protocol, adjust it to match your setup. In Windows PowerShell, use the built-in curl.exe to avoid differences with command aliases. If the explicit request works but regular browsing doesn't, check the system and browser proxy settings. If it fails too, check the listener, node, and DNS before expanding traffic routing.

curl.exe --proxy http://127.0.0.1:10808 --head https://example.com/

Distinguish the system proxy, automatic configuration scripts, and TUN

The system proxy page may have manual proxy settings, an automatic configuration script, and automatic detection enabled at the same time. An old script URL or settings left by another app can make traffic follow a different route than the interface suggests. Note the original settings, stop other tools that change the proxy, and use only the one method needed for this test. Organization-managed devices may block changes or restore settings automatically. Contact the device administrator instead of repeatedly trying to bypass those controls with elevated permissions.

Consider TUN only when you need to route traffic from apps that don't use the system proxy. Before enabling it, confirm that the active node works through a regular proxy. Then check that the virtual adapter is created, whether the default route changed, and whether the logs show permission errors. Other VPNs, virtual machine networks, and security software can also affect routing. If there's a conflict, pause one related app at a time and compare. Allowing LAN connections isn't a prerequisite for TUN; they solve different problems.

Before exiting, use Clear System Proxy and check that the system settings have been restored. If the client crashed, the system may still point to a local port that is no longer active. Clear the leftover proxy setting manually, then restart the client normally. Keep the previous values—especially if your work setup uses a proxy—rather than deleting every entry. For the basics of system proxy settings and routing, see the quick start guide. To compare platform-specific client behavior, see client comparisons instead of copying settings between operating systems.

Client Crashes: Save the Evidence, Then Isolate the Configuration

Tell the difference between a closed interface, a stopped core, and a background process

A window disappearing doesn't necessarily mean the program crashed; it may be minimized to the system tray. Likewise, a visible interface doesn't prove the core is running normally. Check the taskbar, tray, and process list, then see whether the logs continue to show new requests. If the interface stays open but the core repeatedly exits after startup, check the configuration, ports, and permissions. If the whole app closes as soon as you start it, check system application error logs, the runtime environment, and configuration loading. Android background shutdowns are covered in the next section; desktop troubleshooting doesn't apply directly.

Before troubleshooting, stop automatic restart loops and save the app logs and system records around the time of the error. In Windows, look for the matching error in Event Viewer under Application logs. On macOS, check the system crash reports; on Linux, check the desktop launch output and user-level logs. You don't need to upload everything. Start with the failing module, exit reason, and timestamp. Logs may contain server addresses, user IDs, and subscription credentials. Redact those before sharing, but keep the error type and sequence of events.

Check architecture, installation method, and file permissions

Choose the client for your operating system and processor architecture on the client downloads page. If the app won't start, don't copy executable or core files from different sources; mismatched dependencies can cause more problems. The Windows desktop and classic WPF versions use different interfaces, so follow the instructions for the version you chose. Back up your configuration before switching. On macOS, check the chip type; on Linux, check the package format and system architecture. Don't choose a package based on its file extension alone.

The app, user data, and log directories need normal write access. Read-only locations, protected folders, low disk space, and files locked by sync software can prevent settings from saving or the core from starting. Check the specific path in the error, then move the data to a location you can write to. Don't loosen permissions across the entire drive. If security software reports a blocked file, check the warning and file source first instead of turning off protection. On managed devices, follow your organization's installation policy.

Reproduce the issue with a minimal setup without wiping the original data

Back up your data, close the client, and create a separate test configuration following its data-directory instructions. If the client supports portable mode or a separate data directory, use the documented method instead of guessing a directory flag. Import only one known-working configuration into the test environment and temporarily disable TUN, custom routing, and extra overrides. If the minimal setup starts, the original configuration or an extension setting is more likely to be the cause. If it still crashes, check the installation environment, architecture, and system error logs.

To restore your original setup, add items back one at a time in this order: subscription, basic proxy, routing, then TUN. Start and test after each change. If one step reliably triggers the error, keep track of what changed. Configuration syntax errors usually show the field or location in the logs. If you edited JSON by hand, check the quotation marks, commas, and value types; don't use bulk text replacement to patch every file. If an auto-generated file is wrong, fix the source setting too, or the same error may return when you switch nodes.

If the issue started after an update, note which interface version, core family, and configuration changed before and after the update instead of relying on memory. When reporting the issue, include your operating system, processor architecture, launch method, reproduction steps, and whether the minimal configuration also fails. If it happened after waking from sleep or switching networks, include the power and network changes. Once resolved, check that the system proxy clears when the client exits, so a local app issue doesn't leave the whole system offline. Restore automatic startup last.

Android Troubleshooting: VPN Permissions, Background Activity, and Per-App Proxy

Make sure the VPN service is running—not just the app

v2rayNG → Connect. The first time you start it, Android asks for VPN permission. This lets the client route traffic on the device through Android's VPN service; it doesn't mean you're connected to a remote server. After granting permission, check the persistent notification, app logs, and actual connectivity. If the permission prompt keeps returning, check whether another VPN app is active and whether a work profile or device management policy limits VPN access. Only one VPN usually controls a user profile at a time, so stop other traffic-routing apps before testing.

Also distinguish VPN mode from proxy-only mode in the settings. VPN mode uses the system interface to route eligible app traffic. Proxy-only mode mainly provides a local proxy endpoint that apps must use themselves. In proxy-only mode, the client's own test may work while regular apps remain unaffected. Note your current mode, switch to VPN mode for a basic connectivity test, and then consider advanced use cases. If Android is set to always-on VPN or to block connections outside the VPN, make sure the setting applies to the client you're using.

If the connection drops when the screen locks, check battery and background limits

Go to System Settings → Apps → v2rayNG → Battery and check whether background activity is restricted. Allow ongoing operation using the options available on your device. Menu names vary by manufacturer and may appear as background activity, autostart, or battery optimization. First, make sure the app can show its ongoing notification, then test with the screen locked. Disabling notifications doesn't necessarily stop the service, but it reduces the information you can observe. Battery settings, power-saving mode, and background data limits can directly affect whether the connection stays up.

Record what happens with the screen on, after locking it, and after switching networks. If the connection fails only after the screen has been locked for a while, check background restrictions. If it fails after switching from Wi-Fi to mobile data, check network recovery and whether the old connection is rebuilt. If mobile data always fails but Wi-Fi works, check Data Saver, the app's mobile data permission, and the mobile network itself. After changing battery settings, reconnect and repeat the same screen-lock test. A saved setting alone doesn't prove the issue is fixed.

Check which way the per-app proxy list works

v2rayNG → Settings → Per-app proxy. First check whether the mode proxies only selected apps or bypasses selected apps. These lists work in opposite directions: in the first mode, an app must be selected to use the proxy; in the second, an app must not be excluded. If the browser works but another app doesn't, check whether it's on the right list and whether a related component belongs to a separate app. Web redirects, sign-ins, and downloads may be handled by system components, so the same app doesn't always handle the entire task.

To check whether the app list is the issue, temporarily turn off per-app proxying so the target app is included in basic traffic routing. Stop and reconnect the VPN, then test again. If it works, check the list direction and which components are included. If it still fails, look at the app's own proxy, DNS, destination service, and UDP support. Don't enable multiple filter sets at once; the more rules you add, the harder it is to see why traffic was excluded. Work profiles and personal profiles may have separate app instances, so check the routing scope allowed by the system in each profile.

Reconnect after switching networks, then check core compatibility

Switching between Wi-Fi and mobile data changes the local address, routes, and reachable paths. Existing connections may not recover immediately. Stop the connection, wait for the network to stabilize, then reconnect and run a real connection test. If only one network fails, see the node timeout and DNS sections instead of reinstalling the app. After enabling bypass for LAN addresses, test access to local devices separately. That option changes routing for local destinations; it doesn't restore access to remote nodes or replace per-app proxy settings.

On Android, start with v2rayNG. Choose v2flyNG only when you need a specific configuration supported by the v2fly core. Select the right package for your device architecture from the Android downloads. Keep your original subscription and essential settings before switching, and don't let two VPN apps compete at the same time. If the issue involves a protocol extension, ask the provider which core the configuration targets instead of copying every advanced setting. Finally, follow the VPN permission and background settings guide and test with the screen locked, after switching networks, and after disconnecting manually. Confirm the connection recovers reliably, not just immediately after you tap Connect.