V2Ray Troubleshooting
Guide

No internet access: narrow down the problem

A running client only confirms that the interface or core is in some working state; it does not prove that browser requests are reaching the remote server. Temporarily disable TUN mode and the system proxy, then visit a site that normally works without a proxy. If that fails too, check Wi-Fi, your gateway, captive portal sign-in, or system network settings before changing servers. If internet access still fails after you exit the client, check for system proxy settings that still point to localhost. Restore the original settings and test again.

Establish a repeatable baseline test

Record the client, selected server, routing mode, system proxy state, and local listening port. Clear old entries in the log, then visit the same HTTPS page. Browser cache can mask the actual result, so try a new private window and check that no extension is managing the proxy independently. Test one page at a time and note when you tested. Don’t switch servers, enable TUN, and change DNS all at once; if the connection comes back, you won’t know which change fixed it.

In v2rayN, first make sure the intended entry is selected in the server list and that the core starts without an immediate error. On desktop, check the system proxy mode in the status area or tray menu. Compare the local port with the port entered in the app—don’t use the remote server’s port as your local proxy port. A mixed listener may accept more than one proxy protocol, but its capabilities depend on the core and current settings. The port number alone doesn’t tell you what it supports.

Distinguish an app that isn’t using the proxy from an unreachable remote server

If the log shows nothing for the current request, check whether the browser follows the system proxy, has its own proxy configured, or is routing the destination directly. If a request appears and is immediately followed by a remote connection error, focus on the next section. A direct connection entry in the log doesn’t mean the server is broken; it may be expected for LAN traffic or a custom routing rule. Test with a destination that should clearly use the proxy, not an address that may be excluded.

Use the command below to specify a local HTTP proxy and bypass system proxy discovery. The example’s 10808 port applies only if the corresponding local listener is enabled; otherwise, replace it with the port configured in your client. On Windows, run curl.exe in a terminal; on macOS and Linux, use curl. The example uses a public test site. For troubleshooting, you can substitute an HTTPS address you’re authorized to access.

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

If the command can’t connect to the local port, check the listener, port conflicts, and whether the core started. If the local connection succeeds but the remote request times out, check the server settings and network path. An HTTP response confirms that this request went through the proxy and received a response; it doesn’t mean every app or destination is working. If the browser still fails, check extensions, its own proxy settings, secure DNS, and certificate warnings one by one.

Keep the configuration minimal while recovering

Temporarily use one server with verified settings, keep the default routing approach, and disable additional traffic-routing tools. Don’t delete the entire configuration directory as a substitute for diagnosing the problem; that could remove subscription groups, routes, and personal settings. Back up first, then restore items one at a time to find conflicts. If you see a certificate warning, don’t disable certificate verification. Check the device clock, destination hostname, and certificate, and confirm whether the network requires an authorized inspection proxy.

Server timeouts: check the port and handshake separately

A timeout can have several causes. It may happen while resolving the server hostname, establishing a transport connection, completing an encrypted handshake, or requesting a destination after the proxy connection is established. Expand the test result and logs to see which address and step timed out before switching servers. If just one entry fails, check its settings first. If every entry fails on the same network, check the local connection, system clock, and whether another proxy app is routing traffic.

TCPing is not a complete connection test

TCPing mainly checks whether a TCP connection to a port can be established. Success doesn’t confirm authentication, TLS, the transport path, or access to the destination. TCP results also don’t apply directly to configurations that use a different underlying transport. v2rayN’s real connection test sends a request through the proxy, making it closer to actual use, but the result still depends on whether the test destination is reachable. If the test fails but your usual destinations work, check the test address and timeout settings before removing the server.

For a TCP service, use this system command in a Windows terminal to check the port. The hostname and port are examples only; replace them with the values in your server entry before running the command. This checks the port layer, not whether the protocol settings are correct. A third-party port checker is no substitute for a local test: its network path is different from yours.

Test-NetConnection -ComputerName example.com -Port 443

Check how the connection settings fit together

Reopen the server editor and check the address, port, protocol, and identity fields in order. Then verify the transport type and any required path, hostname, or service name. A WebSocket path and request host, a gRPC service name, or a TLS server name can all affect the handshake; these values are not interchangeable. Importing a complete share link is usually more reliable than copying settings by hand, but make sure chat software hasn’t truncated the link or altered its escaping.

For TLS errors, check the system date and time zone first, then confirm that the server name matches the server configuration. For a REALITY entry, also verify the public key, short ID, server name, and client support. Don’t combine settings from different servers. If the provider changed its settings, update that subscription group and select the entry again. A manually saved copy in an old window may still contain expired connection details.

Narrow down the network with a controlled comparison

Keep the same device and server configuration, and switch only the network—from your current Wi-Fi to a mobile hotspot. If it works on the hotspot, investigate DNS, egress, or access policies on the original network. If it fails on both, use the same network to test another known-good configuration. Change one variable at a time; don’t also switch devices, servers, or cores. Intermittent timeouts may come from remote rate limits or an unavailable service. Client settings can’t fix a server that has stopped listening.

Avoid repeatedly testing the entire list with high concurrency. Many simultaneous handshakes can trigger server connection limits and use enough local bandwidth to make healthy entries appear to fail. Test one entry first, then compare a small number. For a more complete first test, see Real Connection Testing and Verifying Proxy Use. Record the failing stage rather than simply marking a server as “broken.”

Subscription errors: distinguish fetching from parsing

Updating a subscription involves two separate steps: the client requests the subscription URL, then parses the response into server entries. A failed request, empty response, or unsupported format can all leave the list unchanged. Check the update message and logs to see whether a valid response was received. If existing servers still work, don’t delete the group. Keeping the old entries prevents a temporary update failure from leaving you without a usable configuration.

Check the import menu and link type

v2rayN manages subscription URLs through subscription groups. Usually, you open the subscription group settings, add a label and URL, then update from the subscription group menu. In v2rayNG, add the URL under Subscription settings in the side menu, return to the main screen, and update the subscription. Menu wording may vary between versions, but entering the URL and updating are separate actions. Saving the URL doesn’t download the subscription. If you can’t find the menu, check which client you’re using.

A subscription URL is usually an HTTPS link, while an individual share link often starts with a protocol name. They serve different purposes: if you enter a single share link as a subscription URL, the client may try to fetch it as a web address and fail. Check for spaces, line breaks, Chinese punctuation, and an incomplete link. A QR code is just a way of carrying text; scanning it doesn’t mean its contents are suitable for the import option you chose.

When a request fails, check the access path

First check that the device clock is correct, ordinary websites load, and the subscription hasn’t expired or been disabled by the provider. If you see an authorization error or access denied, ask the link provider to check your access; changing local ports won’t fix permissions. Opening the subscription URL in a browser only confirms that the browser’s route works. The client may use a different route to update subscriptions, for example because of browser extensions or different system proxy settings.

The v2rayN subscription menu may offer options to update through or without the proxy; use the wording shown in your version. If the subscription service is only reachable through an existing proxy, select a working server and connect before choosing the appropriate update option. If you don’t have a working proxy, don’t try to update through a broken connection. Use direct access or another network permitted by the provider. Never send a private subscription URL to an unfamiliar conversion service just to test it.

What to do when an update succeeds but adds no servers

If the request succeeds but the list remains empty, check whether the server returned a login page, error page, or redirect instead of subscription data. An HTTP success status doesn’t guarantee that the response contains a subscription. Common formats include multiple share links, encoded link collections, or structured configurations for specific clients; not every format can be imported into every client. Choose a subscription format explicitly intended for your client rather than guessing compatibility from a file extension.

Next, check the group filter and search box. The servers may have imported but be hidden in another subscription group or filtered out by the current search. Clear the search, select the right group, and compare the entry count and error message. If only some entries failed to import, check their protocol, transport, and core support. Other successful entries don’t rule out a format or settings issue. Fix one entry before updating the whole list.

Subscription updates may overwrite manual changes in a group. If you need to keep personal adjustments, record them first and check how the client handles updates before deciding whether to put them in a separate entry. When moving to another device, remember that a subscription URL, server list, and full client backup contain different information. See V2Ray Subscription Links: Import and Format Guide for details on formats and import options. For your first import, follow the steps in Getting Started.

Slow speeds: separate throughput, latency, and load

Slow page loads, low download speeds, and video buffering don’t necessarily have the same cause. A page’s first load is more sensitive to DNS resolution and handshakes; large downloads depend more on sustained throughput; interactive apps are sensitive to latency and packet loss. First note which app and destination are slow, and when. Then choose a suitable test. Don’t compare a page load time with a different route’s large-file download speed, or treat a connection test as a measure of maximum bandwidth.

Rule out local network issues and competing traffic first

Pause system updates, cloud sync, and other high-bandwidth tasks to make sure background downloads aren’t saturating your connection. If Wi-Fi is weak, move closer to the access point or compare with a wired connection. Keep the client settings unchanged and test whether direct access is also slow; if all traffic is affected, start with your local connection. Thermal throttling, high CPU usage, or power-saving settings can also reduce sustained throughput, especially on mobile devices after prolonged use.

Run one test at a time, using the same destination and file for roughly the same duration. Server speed tests often use small requests, so they reveal only part of the picture. Testing the whole list in parallel uses bandwidth and may saturate it with the tests themselves. Start with a few candidates, then verify them with real-world tasks. Check whether the app reports bytes or bits per second; the units aren’t directly comparable. A brief peak also doesn’t represent sustained speed.

Distinguish server load from destination limits

Keep the network and destination fixed, and change only the server. If one server is clearly slower across multiple destinations, it may be affected by server load, bandwidth, or its upstream route. If all servers are slow for just one destination, check that service’s rate limits, caching, and connection policies. Increasing local thread counts won’t fix a remote server under resource pressure. Comparing peak and off-peak results can help, but keep the test conditions the same before drawing conclusions about congestion.

A fast real connection test and a slow download can both be true: a short request may finish quickly while sustained traffic is affected by congestion or rate limits. Conversely, a connection with a slower handshake may sustain higher throughput. Focus on whether the task you care about improves, not on making the number in the server list smaller. For more detailed checks, see Layered Troubleshooting for Servers, Routes, and Local Settings. Record comparisons before switching routes.

Be cautious when changing transport, Mux, or routing

Mux carries multiple logical requests over fewer underlying connections. It can reduce the overhead of repeated connections, but on some routes and server combinations, requests may share the same connection’s congestion. More concurrency isn’t always faster, and not every protocol is suited to the same multiplexing approach. If Mux is the only recent change, restore its previous value and compare. If the server requires fixed transport settings, don’t change WebSocket to another transport just to chase speed.

Routing can also make only part of a page appear slow. The page itself, images, and login API may use different hostnames and match different outbound rules, so the page frame loads while resources stall. Check the logs and rules for slow requests to confirm they’re taking the expected path. DNS caching and connection reuse can affect retests. After changing a rule, restart affected connections and, if necessary, the app. An existing connection may still work even when a new rule hasn’t taken effect.

If speed improves, record the change that helped and undo unrelated experiments. A small number of necessary adjustments is often more reliable than a collection of “optimized” settings. If performance remains poor after ruling out local issues, give the provider the time window, destination type, and comparison conditions. That’s more useful than simply reporting that the internet is slow.

DNS issues: find out where resolution happens

DNS maps hostnames to addresses, but a proxy setup can involve several resolvers. The operating system may resolve names, the browser may use its own secure DNS, and the client core may resolve names according to its configuration. With SOCKS, the app may also send the hostname to the proxy server for resolution. First determine whether the server hostname or destination hostname is failing, and which path the request uses. Changing every resolver at once obscures the cause and can create new dependency loops.

Start with system resolution and client logs

If the log says the server hostname can’t be resolved, the connection may not have reached the remote server. Changing the destination site’s route usually won’t help. First check whether the hostname resolves in a system terminal. On Windows, use nslookup; on macOS and Linux, use an available system DNS tool. The command below is only a syntax example. If system resolution works but the client still fails, check the core’s DNS settings and which upstream it actually uses; they don’t necessarily share a cache.

nslookup example.com

Getting multiple addresses is common; a different result from another device doesn’t by itself indicate a problem. Content delivery services return different results depending on network location and policy. Successful resolution only means an address was returned, not that it’s reachable. A resolution timeout could mean an unresponsive upstream, an incorrect request path, or a local network restriction. If the issue appears only after switching networks, reconnect the client and check for leftover DNS settings on the previous interface.

Compare local and remote resolution with SOCKS requests

If a SOCKS listener is enabled, use the two commands below to compare results. The first usually resolves the destination hostname on your device; the second sends the hostname to the proxy server for resolution. Replace the port with the one configured locally. If only remote resolution works, investigate local DNS for the destination hostname, while checking the logs for differences in address selection. This test doesn’t prove that all DNS traffic follows the same path.

curl --socks5 127.0.0.1:10808 --connect-timeout 10 -I https://example.com/
curl --socks5-hostname 127.0.0.1:10808 --connect-timeout 10 -I https://example.com/

A browser’s secure DNS may bypass the system resolver. If DNS works in a terminal but the browser fails, check the browser’s own settings. Temporarily switch it to use system DNS for comparison, then decide which setting you need. Clearing the browser cache won’t necessarily clear the system or core cache, and vice versa. Close existing connections first, then clear the cache at the layer where the issue occurs. Otherwise, cached results may look like a routing rule failure.

Avoid DNS bootstrap loops and rule mismatches

If an encrypted DNS upstream uses a hostname, the connection to that upstream may itself need DNS resolution. This can create a loop if resolution depends on a proxy connection that hasn’t been established yet. Set up bootstrap resolution or an explicit upstream route using a method supported by the core, rather than repeatedly adding the same unreachable upstream. Corporate intranet hostnames may only resolve through the local network’s DNS server; sending all of them to a public resolver can make work services inaccessible.

Hostname rules and IP rules may match at different stages. The snippet below shows a LAN direct-routing rule for native Xray routing, illustrating how the fields relate. It’s not a complete configuration and shouldn’t be pasted into an arbitrary client editor. direct must match an outbound tag that actually exists. Rules are usually evaluated in order, and geodata files must be available. In a graphical routing editor, use the corresponding fields to express the same rule.

{
  "type": "field",
  "ip": ["geoip:private"],
  "outboundTag": "direct"
}

If the issue occurs only on IPv6 or dual-stack networks, compare the returned address family with what the remote server can actually reach. Don’t disable IPv6 as a permanent fix without checking whether the cause is address selection, routing, or upstream support. With TUN virtual address mapping, apps may need to reconnect after TUN is disabled. Verify regular hostnames, intranet names, and real services to make sure a fix for one test site hasn’t broken other access.

System proxy not working: check where traffic enters

A system proxy is a network setting that apps can choose to follow; it doesn’t force all traffic through a proxy. Some programs use it, some have their own proxy settings, and others ignore it entirely. So a browser working while another app fails doesn’t prove that v2rayN isn’t running. First confirm that the local listener works with an explicitly proxied request. Then check how the target app gets its proxy settings, and only then consider whether you need TUN.

Check whether the system settings were actually applied

In v2rayN, choose the option to set the system proxy, then check the address and port in your operating system’s network settings. On Windows, the current user proxy, automatic configuration scripts, and settings used by some system components may differ. On macOS, proxy settings belong to a specific network service, so check the active service after switching between Wi-Fi and Ethernet. On Linux, desktop environments and terminal apps may get proxy settings from different places. Don’t rely on the checked state in the client menu alone.

If the settings revert immediately after being applied, check for another proxy app, browser extension, device management policy, or network security tool. During troubleshooting, let only one program manage system proxy settings to prevent tools from overwriting each other. Repeatedly toggling the setting won’t resolve a conflict. Before exiting the client, clear the system proxy and confirm that the network works again. If settings remain after an unexpected shutdown, restore them manually in the operating system; the local listener may no longer be running.

Check the app and terminal environment separately

For apps that support their own proxy settings, enter the loopback address and actual listening port, and select the matching protocol. HTTP and SOCKS aren’t interchangeable labels; the same port number can accept both only if the listener is configured to support them. Terminal tools may also read HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, or exclusion variables. An old value can send requests to a port that’s no longer active. Remember that environment variable values may contain private information.

If an app has its own bypass list, it may connect directly to LAN addresses or specific hostnames. That’s app behavior and isn’t controlled by the server selected in the client. Send the same request to the same destination through an explicit proxy and through the app, then compare the logs. If the app’s request doesn’t appear at all, check how traffic enters. If it appears as a direct connection, check routing. If it enters the proxy and then fails, check the remote side. This keeps three different problems from getting mixed together.

With TUN, verify traffic capture before split routing

TUN captures traffic through a virtual network interface, making it useful when you need broader traffic coverage. It also adds variables such as permissions, system routes, and DNS. First disable other VPNs and overlapping virtual network tools, then grant the permissions requested by the client. Some Windows operations may require administrator access; follow the prompts on other desktop systems. Don’t run the entire client with elevated privileges indefinitely as a default fix for every problem.

If even direct sites stop loading after you enable TUN, turn it off and confirm that the regular local proxy still works. Then check whether the virtual interface was created, the default route is correct, and DNS was captured. Capturing traffic doesn’t guarantee the rules are right. If you can’t access a local printer or work network, check bypass rules for private addresses and intranet hostnames. Don’t delete system routes or copy someone else’s full network configuration; interface names and address ranges often differ.

After troubleshooting, decide which traffic entry method to keep and restore a configuration you can explain. System proxy and TUN can work together in some setups, but test them separately while diagnosing a problem. For definitions of “system proxy,” “routing,” and “core,” see the glossary. For your first connection, follow Getting Started to verify the system proxy path before moving on to TUN.

Startup failures and crashes: distinguish the interface from the core

Startup problems can look at least three different ways: the main window won’t open, the window opens but the core exits immediately, or the entire client closes during use. First identify which is happening, then look for evidence that matches. A working interface doesn’t mean the core executable can run, and the core can exit without closing the interface. Look for details in the client logs, system event records, or full startup messages. Don’t rely on a screenshot saying “won’t open,” and don’t repeatedly reinstall before recording what happened.

Check that the package matches your system

For desktop use, v2rayN is the recommended option. Choose a download on the downloads page that matches your operating system and processor architecture. Windows Desktop and WPF are different interface versions, with potentially different runtime requirements and failure modes; don’t mix their files in the same directory. For macOS, distinguish Apple Silicon from Intel. For Linux, check both the processor architecture and package format. Installers and archives are used differently; don’t run the program from inside an archive viewer.

If you see a runtime requirement on first launch, install the component specified for your package. Don’t rely on memory and install a similar-looking runtime. If your operating system version doesn’t meet the software’s requirements, adding more components may not help. Windows folder permissions, macOS security prompts, and Linux graphical sessions or libraries can all affect the interface. Read the specific error before acting; don’t disable system protection globally or grant write access to every file.

The interface opens, but the core exits

Look for the earliest error in the core log; many subsequent connection failures may just be knock-on effects. Configuration syntax errors, unsupported fields, missing data files, occupied local ports, and insufficient execute permissions all require different fixes. If you recently changed cores, check whether the protocols and transports in your configuration are supported. v2rayN can manage different cores, but a field supported by one core may not be supported by another. Changing the core name alone won’t resolve a configuration compatibility issue.

For a local port conflict, first check whether another client or an older core is still running. Use the system process list and port information, then close duplicate instances normally. Don’t force-quit a process just because its name looks familiar; another app may depend on it. Changing the port can avoid a conflict, but you’ll also need to update the system proxy, browser, and app-specific proxy settings. Otherwise, the core may be working while apps still try to connect to the old port.

Isolate configuration problems with a minimal setup and a backup

If a crash started immediately after importing a configuration, updating a subscription, or changing a route, back up the current data and test with a separate configuration. If the installation method allows it, follow the software’s instructions to use a new user data location. Don’t delete the original directory without a backup. Keep the test to one complete server entry and basic settings. If the clean setup works, restore subscriptions, routes, and interface preferences one at a time to find out whether a data item is damaged or the overall environment is at fault.

If security software quarantines a file during an update, check its quarantine history and verify the download source and package contents. Don’t add a broad exclusion for the entire downloads folder. Low disk space, a read-only configuration directory, or a file lock from a sync service can also prevent settings from saving or cause old values to return on startup. Move data to a local location that meets the client’s requirements and that your user account can access, then test writing to it. Exit the client completely before moving data so two instances don’t modify it at once.

For intermittent crashes, note whether they occur after waking from sleep, switching networks, or enabling TUN. Check whether the system terminated the process because of resource pressure. Increase log verbosity only while reproducing the issue, then restore it to avoid generating excessive logs. See Initial Setup for Windows and macOS for first-run guidance. Reinstalling fixes some file problems, but won’t automatically resolve conflicts with old settings or permissions.

Android troubleshooting: permissions, background use, and per-app proxy

On Android, v2rayNG is the primary option; v2flyNG is an alternative that uses the V2Fly core. Their traffic handling differs from the system proxy on desktop: VPN mode commonly uses Android’s VpnService to create a local traffic tunnel. A VPN icon in the status bar mainly confirms that the system tunnel exists; it doesn’t mean the remote server completed its handshake. Select a server, check the connection log, and test a real app request. Don’t judge connection success by the notification icon alone.

VPN permission and conflicts with other services

The first time you start VPN mode, Android asks for permission to establish a connection. Confirm the app’s source, then allow it. If the prompt doesn’t appear or its buttons don’t work, check whether an overlay, screen filter, or system restriction is interfering. Work profiles, managed devices, and parental controls may also restrict VPN access. Follow the device’s management policy rather than trying to bypass it with client settings. If permission was revoked, reconnect and confirm the system prompt; updating the subscription alone won’t restore it.

Usually, only one of these VPN services can be active at a time for a given user. Another VPN, firewall using a VPN interface, or network filtering tool may replace the current connection when it starts. Exit other apps that use the VPN service normally before connecting the client. If always-on VPN or “Block connections without VPN” is enabled, check which app it’s tied to. A policy left behind after an app is removed or disabled can keep the device offline.

For disconnects when the screen locks, check power management first

If the app works in the foreground but disconnects after the screen locks, look at background restrictions before blaming the server. Check the client’s battery settings, allow necessary background activity, and relax overly strict power-saving limits using the options available on your device. Some devices also require permission for autostart or keeping the app in recent apps, but menu locations vary. No single switch fixes every brand. Verify by leaving the screen locked for a while, then checking whether the logs and notification are still present.

If the service is still running but the first request after unlocking times out, an old connection may have stopped working when Wi-Fi and mobile data switched. Stop and reconnect, then check whether service returns immediately. Also see whether the system turns off Wi-Fi during standby. Check Data Saver, background mobile data restrictions, and Battery Saver separately. Change one setting at a time rather than disabling every power-saving feature; the goal is to allow necessary background activity without keeping the device in a high-power state.

Check what the per-app proxy selection means

After enabling per-app proxy in v2rayNG settings, confirm whether the list means “only selected apps use the proxy” or whether it’s set to bypass selected apps. It’s easy to misread the checkmarks. You may need to reconnect the VPN for list changes to apply to a new session. System components, download services, and in-app browsers may also make requests on behalf of a different app. Test actual behavior instead of selecting large numbers of system apps at random.

If a browser works but a chat or media app doesn’t, first test with per-app restrictions disabled, then check whether those apps are excluded. They may also use different transports or long-lived connections; a working browser doesn’t prove every protocol is working. For work profile apps, keep the user-space boundary in mind: a client in your personal profile may not be able to route requests from another profile. Use the system-supported setup rather than treating a permissions boundary as a server problem.

Installation, updates, and moving to another device

If installation fails, check the architecture, available storage, and system message first. Most devices that support the architecture can use arm64; if you’re unsure, follow the download page’s guidance for the general option. Don’t install packages from unknown sources or with a mismatched signature over the existing app. If there’s a signature conflict, identify the current installation source and back up subscriptions and settings before deciding how to migrate. Uninstalling may remove local configuration, and reinstalling won’t restore a private subscription URL automatically.

After updating or switching between v2rayNG and v2flyNG, check VPN permission, battery settings, the selected server, and the per-app list separately. Apps with similar names don’t automatically share data, and core support should be checked independently. For detailed system settings, see VpnService Permissions, Battery Optimization Exceptions, and Per-App Proxy. If everything in this section checks out, return to the timeout and DNS sections and follow the same connection layers instead of reinstalling again.