Troubleshooting Guide · 8 Symptoms

V2Ray Troubleshooting Guide

First determine whether the issue affects one app, one node, or the entire device. Check the relevant part of the setup, and avoid changing nodes, routing, and DNS all at once.

If you’re installing for the first time or haven’t imported a subscription yet, follow the quick start guide: import a subscription, choose a connection method, connect, and verify. If you can reproduce a specific issue, choose a symptom below. This guide is organized by the part of the connection that’s failing; once fixed, return to the tutorial to verify your connection.

01 · Connection baseline

No internet: restore a direct-connection baseline first

If webpages stop loading after you enable the client, first check whether the device can connect to the internet on its own. Turn off the client’s traffic interception, then visit a site that normally works without a proxy. If it still fails, check the Wi-Fi, gateway, or system settings first. If access returns immediately, investigate the client connection path. Compare results on the same device, network, and URL—don’t use results from two different devices as substitutes.

Check stopping traffic interception separately from quitting the app

When using v2rayN on desktop with the system proxy enabled, first clear the system proxy in the client, then quit the app. If a virtual network adapter is also enabled, disable it separately. Next, open the operating system’s network proxy settings and make sure they don’t point to a local address belonging to a client that’s no longer running. If the device originally used a proxy or automatic configuration script provided by your organization, restore it according to your records rather than turning everything off. On mobile, check the system network settings to confirm the VPN session has actually ended.

If the baseline connection still fails, check whether other apps can reach the same site, then test with another device on the same network. If both devices fail, check whether the network requires sign-in or contact the network administrator. If only this device fails, consider whether it recently switched from wired to wireless, woke from sleep, or is still using outdated static network settings. Test in a new browser tab; an old page may still appear because its content is cached locally.

When reconnecting, enable only one connection method

Once direct access works again, start the client, select a valid node you’ve previously confirmed works, and wait for the core to finish starting. Test with either the system proxy or VPN traffic interception—not both—and don’t change routing presets at the same time. On desktop, try a browser that follows the system proxy, then compare it with a site you normally access directly. If both fail, check whether the core is listening successfully. If only one site fails, note the logs for that URL and distinguish routing, DNS resolution, and the destination site’s response.

When checking logs, start recording before sending a new request. Startup logs only show that the process reached a certain stage; they don’t prove the browser passed a request to it. If you’ve confirmed the log level records access but no entry appears during the request, check how the app connects to the client first. If the log clearly shows a timeout connecting to the remote server, see Node timeouts. For a name resolution error, see DNS issues. Don’t treat repeated copies of the same log entry as separate problems.

Compare direct and intercepted connections

Comparison resultWhat to check firstNext step
Still fails after stopping traffic interceptionThe problem may be outside the clientCheck for leftover system proxy settings, network authentication, and device connectivity.
Direct access works; multiple sites fail when traffic interception startsCheck the local proxy endpoint or nodeConfirm the core has started, then retest with a known-good node.
Only one app failsApp proxy settings or reused connectionsRestart the app and check which proxy and DNS settings it actually uses.
Only one domain failsDestination DNS, routing rules, or site issueSend a fresh request to that domain and compare DNS, outbound selection, and response status.

After fixing the issue, repeat the operation that originally failed, then test a site that worked before to make sure the fix hasn’t changed how other traffic is handled. If a device restart is the only way to restore access, preserve the logs the next time the problem occurs and test stopping traffic interception, restarting the app, and reconnecting to the network separately. Note which step restores access first to distinguish leftover system settings, an app connection that wasn’t re-established, and a network outage. Don’t assume a successful restart has identified the root cause.

02 · Node connection path

Node timeouts: distinguish port, handshake, and destination request failures

A timeout in the latency column doesn’t necessarily mean the node is down. Port checks, protocol connections, and webpage probes test different stages and may use different test destinations. First note which test failed and whether the actual browser request also fails. If only a batch test reports an error, test one node on its own before deleting a whole group or drawing conclusions about every node from the same results.

First check whether the timeout affects one node or a group

On the same device and network, use two previously working nodes to reach the same destination. If only one fails, check that node’s active configuration and service status first. If an entire group fails but other groups work, check whether those nodes share a server address, port, or service endpoint. If all groups fail at once, revisit core startup, network changes, and DNS resolution—especially whether the issue began right after switching connection methods.

Use the service provider’s settings as the source of truth when checking a node: the server address, port, protocol, transport, and security settings must match as a set. The server name used for TLS may differ from the connection address. Conversely, don’t guess at a replacement server name or ignore certificate validation just to make an error disappear. If the logs report a certificate time error, check the device clock and time zone first, then ask the provider to verify the certificate. If the error started after a subscription update, compare protocol fields before and after; don’t compare only the display names.

Test the TCP port and local listener separately

A startup failure and a remote timeout are two different issues. If the core never starts listening, a local check will fail earlier. The following interactive check is for Windows PowerShell and TCP-based node ports only. Enter the server address and port already shown in the client when prompted. It makes a standard TCP connection; it does not verify the proxy protocol or use the browser’s system proxy. Don’t enter a subscription URL, a URL with a path, or credentials.

$server = Read-Host 'Node server address'
$port = [int](Read-Host 'Node TCP port')
Test-NetConnection -ComputerName $server -Port $port -InformationLevel Detailed

If TcpTestSucceeded is true, that only means this TCP connection succeeded. A false result alone doesn’t prove the service is down; DNS results, the current network path, and the service listener can all affect it. If the port is reachable but the client reports a handshake failure, check the protocol, security layer, and core support. If the handshake succeeds but the webpage probe still fails, check whether the test URL is reachable and whether the routing rules send the request through the expected outbound. No response to a regular ping likewise doesn’t prove the port is unavailable.

Keep a consistent set of results for retesting

If the client’s probe destination is unreachable, choose a test target whose status you can verify and send a real request. Test a small page first, then open the resource that originally failed. Note which stage fails first: port, handshake, or page. See Real connection tests and first-time verification. If the issue occurs only on one network, repeat the same steps on a known-working network you’re authorized to use. This can show that the issue is related to the network environment, but it can’t identify the specific cause on its own.

When fixing the issue, update the subscription or reimport the correct configuration if the provider has confirmed that the old endpoint is retired. If the core doesn’t recognize a protocol field, use a configuration supported by the client. Keep the old configuration until the new one passes a webpage test, then remove duplicates. Don’t use a longer timeout to mask an error that always points to the same field. Timeout settings are worth comparing only when the connection succeeds occasionally and the logs show no consistent configuration error.

03 · Subscription updates

Subscription failures: distinguish fetching, parsing, and saving

If a subscription update fails, don’t delete the old group yet. An update has three steps: requesting the subscription URL, parsing the response, and writing the results to the group. A successful download doesn’t mean the response can be parsed, and a larger list doesn’t mean the selected node was replaced. First note the group, the last successful update time, and which nodes are currently working. Update only the affected group so results from other groups don’t get mixed into the logs.

Fetch failed: check which connection path the update request uses

Confirm the subscription URL comes from a currently valid service endpoint and doesn’t include quotation marks, line breaks, or trailing spaces. Check whether the client reports a DNS resolution failure, a connection timeout, or a response status code from the server. For an unauthorized or forbidden response, check authorization and whether the URL has changed through the provider’s management portal. If the server redirects, make sure the final response contains subscription data rather than a login page. Don’t repeatedly edit URL parameters by hand.

In v2rayN, if your version offers both direct and proxy-based updates, keep the current configuration and test each method once for comparison. If direct access is unavailable but a working node is available, use it to test a proxy-based update. If the current node itself is down, don’t rely on it to fetch a replacement. Instead, confirm that the subscription URL is accessible over an authorized working network, or ask the provider for a usable configuration. A page loading in the browser doesn’t prove the client’s update request uses the same proxy settings or authentication state.

Fetch succeeded but returned no results: check the content and group

The server may return a successful status code while sending a login page, error message, or configuration intended for a different client. Check the client’s parsing result first, then ask the provider to confirm the subscription format and supported clients. Don’t submit the full subscription contents to an online converter or decoder; they may contain credentials that can be used directly. If you can test in an isolated group, keep the original group and create a temporary one for the same URL so an empty response can’t overwrite your working list.

If the list contains entries but they’re not visible in the interface, clear the search field, switch to the updated group, and check for filters hiding entries. If only some nodes import successfully, compare the protocols, transport settings, and client recognition messages for successful and failed entries. A provider adding a field that the current core doesn’t recognize doesn’t necessarily make the entire subscription invalid. On mobile, check the provider’s compatibility notes to choose v2rayNG or v2flyNG; don’t assume all three clients import subscriptions in exactly the same way.

Fix manual updates before restoring automatic updates

Once manual updates work reliably, check the automatic update interval and which proxy method is used. When an automatic task runs, the computer may be asleep, the client may not be running, or the previously selected node may be down. To check the interval, note when you save the setting and when the next task actually runs, then compare with the logs. If manual updates work but no automatic task runs, check the client’s running state and the affected group’s auto-update settings. If the task runs and returns an error, continue troubleshooting the fetch or parsing stage. See How to troubleshoot v2rayN subscription update failures.

Don’t judge success solely by an “update successful” message. Open the target group and confirm the entries were saved, then select a new configuration and test a real connection. If the interface still points to an old entry, select the new one before sending a request. Once automatic updates are working again, confirm they update the same group and don’t overwrite entries you’ve kept manually. If you’re unsure how to create groups, revisit the subscription import steps.

04 · Performance comparisons

Slow speeds: test time to first byte and sustained throughput separately

Slow webpages, slow downloads, and frequent video buffering aren’t necessarily the same performance issue. If a page stays blank for a while and then loads all at once, check DNS, connection setup, and the handshake first. If a download starts promptly but remains slow, look at throughput, concurrency, and load at both ends. Choose a task that reliably reproduces the issue. Don’t use one fast latency test to dismiss sustained slowdowns during a large download.

Keep the target fixed and change one variable at a time

Use the same device and an authorized test target, and test at roughly the same time where possible. Pause system updates, cloud sync, and other high-traffic tasks, then note performance using direct access or the current configuration. If the target can’t be reached directly, don’t record direct failure as zero speed; choose a target both paths can reach for a general connection comparison. For downloads, use the same resource and record both the initial wait and the steady-state speed. Keep units consistent—bytes per second and bits per second aren’t the same.

If the same node works over wired Ethernet but is slow over Wi-Fi, check signal strength, distance, and usage by other devices on the same network. If only one node is slow on the same network, check its path to the destination, service status, and performance during peak hours. If different nodes are all slow for the same resource but work normally with another source, suspect throttling or a service issue at the resource end first. Don’t change both the node and the resource in the same test; you won’t know which change improved performance.

Use timing data to find where the slowdown occurs

If curl is installed on your desktop and a local HTTP proxy endpoint is enabled, use the command below to test an HTTPS request. The example uses a public example domain to inspect timing breakdowns, not to measure throughput. If the local port isn’t 10809, replace it with the HTTP proxy port shown in the client. In Windows PowerShell, use curl.exe as the command name and replace the output target /dev/null with NUL.

curl --proxy http://127.0.0.1:10809 --max-time 20 --silent --show-error --output /dev/null --write-out 'connect=%{time_connect}s tls=%{time_appconnect}s first_byte=%{time_starttransfer}s total=%{time_total}s http=%{http_code}\n' https://example.com/

These values are cumulative times from the start of the command; they aren’t four independent durations you can add together. When using an explicit local proxy, the connection time mainly reflects curl connecting to the local endpoint. That field doesn’t directly show when the proxy connects to the remote server. TLS completion may include the time needed to establish the proxy tunnel, and time to first byte also includes destination processing. When comparing with browser behavior, remember that the browser may reuse connections or use cached content, so the readings don’t have to match. If the command reports an error, check the message and response status first; don’t interpret zero values.

Use retest results to decide whether to change settings

If the first byte is slow and the logs frequently show DNS retries, see the DNS section. For slow sustained transfers, observe CPU usage, network activity, and core logs during the same task. If an error appears consistently, fix it first; leaving verbose logging on indefinitely isn’t an optimization. If the problem occurs only with concurrent tasks, reduce the number of parallel tasks and compare results to see whether one connection is limited or all tasks are competing for bandwidth. Keep a change only if it helps; otherwise, revert it.

If speeds drop only at certain times, record the results for both the affected and normal periods, and confirm you used the same node, target, and route. The provider can use this information to check server load; on the device, check for scheduled updates or backups. If the issue can’t be reproduced, keep the existing configuration and observation notes. Don’t change transport parameters, enable several optimizations at once, or overwrite a working configuration to improve one speed test.

05 · DNS resolution

DNS issues: identify which component resolved which domain

If a domain won’t load while other services work, don’t assume DNS is the cause. First identify whether the error says the domain doesn’t exist, the lookup timed out, or the domain resolved but the connection failed afterward. Also check whether the failing domain is the node’s server hostname or the webpage’s destination domain. The former may prevent the node from connecting at all; the latter usually affects only certain sites or outbound requests. These failures occur at different stages, so don’t blindly apply the same setting to both.

Check resolution paths in the system, app, and core separately

Using the system proxy doesn’t mean the core resolves every domain. A browser may use its own Secure DNS; an app may perform its own lookups; and the connection mode, proxy protocol, and routing settings can affect whether resolution happens locally or remotely. Check the failed request’s logs: does the domain name appear, is a destination address recorded, and do they show whether the app, core, or system initiated the lookup? If there’s no relevant entry, check the current log level and connection method first. Don’t interpret a blank log entry as proof that no DNS request was sent.

On desktop, you can use the command below to check a standard DNS lookup in the system environment. Replace the example domain with an affected domain that you’re authorized to test. Note the DNS server, returned addresses, and error type, then compare them with the client logs. This command doesn’t reflect browser Secure DNS and doesn’t prove the core used the same resolver. If the server name isn’t recognized but the domain still resolves, rely on the query result rather than treating the missing server name as a failure.

nslookup -type=A example.com
nslookup -type=AAAA example.com

Handle lookup failures separately from unreachable addresses

If the lookup times out, check whether the current network can reach the DNS server and whether the client is sending the resolver connection through a node that isn’t connected yet. If you get a domain-does-not-exist response, verify the full domain name and check whether a private domain requires an organization network or a specific resolver. A missing record for one address type isn’t necessarily an error; some sites publish only one. If an address is returned but the connection still fails, investigate the route to that address, the certificate, and routing rules instead of repeatedly changing DNS services.

If the issue appears to be address-family related, record both lookup results and the address used for the actual connection. On a dual-stack device, an IPv6 address in the results doesn’t mean the device has a reliable IPv6 route. A browser’s ability to fall back to another address family doesn’t mean the core or target app behaves the same way. Use an existing client option to test one part of the setup, observe whether the actual request improves, and then decide whether to keep the change. Don’t disable IPv6 across the whole device by default; it could disrupt services that already work.

Check the domain and resolution order used by routing rules

Some rules match domains; others match IP addresses. If an app passes the core an address that’s already resolved, whether a domain rule matches depends on whether the core has the domain information and on the active configuration. If routing also needs to resolve a domain to an address, a failure during resolution can look like a routing problem. Check the matched rule or actual outbound first, then identify which stage changed the request. See Quick reference for related terms and System proxy & routing for the order of checks.

For retesting, close old tabs and restart the affected app. If needed, wait for caches to expire, then test the original failing domain and one that worked before. For private organizational services, confirm that internal domains still use the required resolution path after the fix. Change one DNS setting at a time and note the expected result before and after. To roll back, restore the original resolver and connection mode—not just remove the address you added.

06 · Traffic interception & outbound routing

System proxy not working: check app traffic and routing separately

The system proxy determines whether some apps send requests to the client; routing rules determine which outbound the core uses after receiving a request. Enabling the system proxy doesn’t make every app use it, and choosing routing rules won’t automatically send traffic to the core if it never reaches it. First check whether the request reached the core, then check whether it used the expected outbound. Changing both settings together makes it easy to restore access without knowing why.

Check the local proxy endpoint and app settings

On desktop, start with v2rayN. Check the listening address, port, and proxy type in the client, then compare them with the system proxy settings. If the app has its own proxy options, check whether it’s set to follow system settings or still points to an old port. After enabling the system proxy, restart the app or open a fresh connection to test it. Existing connections may keep using the old path; refreshing a page without establishing a new connection won’t rule that out.

A correctly entered local proxy port still needs the right protocol: HTTP or SOCKS. If an app expects an HTTP proxy but you enter a port that only supports SOCKS, it may reach a local process but still fail to complete the request. Use a trusted test target to compare a request that explicitly specifies the local proxy with one sent by the app itself. If the first works but the app’s traffic doesn’t reach the core, check the app settings or process environment before changing nodes. If the proxy is meant for local use only, don’t expose it on every network interface to solve a connection issue.

Once traffic reaches the core: check rule order and outbound tags

Routing rules are generally matched in list order. A broad rule placed first may prevent later exceptions from ever matching. Multiple conditions in one rule also don’t mean that any one of them is enough to trigger it. Find the outbound actually used by the failed request, then check whether an earlier, broader rule matched it. If you edited a client preset, confirm that the saved configuration is still selected; some changes require reloading the core to take effect.

This routing snippet can be merged into a core configuration and demonstrates an exact match using a reserved example domain. It isn’t a complete startup configuration. Use it only if an existing outbound is tagged direct and your network rules allow direct access to the target. full: matches the entire domain, not its subdomains. Here, AsIs means the routing stage won’t proactively resolve a domain just to match an IP-based rule; it doesn’t mean the app never needs DNS resolution.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "direct"
      }
    ]
  }
}

When testing in your active configuration, merge only the rules you need. Don’t replace the entire routing section or change the existing domain resolution strategy as a side effect. Outbound tags in rules must match their definitions exactly. Test the example rule’s target, a target that should use a node, and a target that should connect directly. Check that all three behave as expected. If only a domain rule fails, first confirm whether the core received a domain name or an IP address.

Choose a fix based on the scope of the failure

If only one app ignores the system proxy, use that app’s supported connection settings first. If many apps fail to reach the core, check the system proxy endpoint and client status, or configure device-wide traffic interception according to your organization’s requirements. Change routing rules only when traffic is reaching the core but using the wrong outbound. Preset names suggest their purpose but don’t replace checking the actual rules and logs. See System proxy vs. routing mode for related concepts.

07 · Startup & processes

Client crashes: distinguish the UI from the core process

No window after double-clicking, a window that disappears immediately, and a window that stays open but can’t connect are three different situations. First check whether the UI and core processes are running, and note whether the issue occurs during startup, configuration loading, or after you click Connect. If a crash interrupts the network, restore the original system connection settings before further testing. Repeatedly reopening the app may overwrite the previous logs, so save the first useful error you can identify.

Check the platform, architecture, and installation method

On desktop, start with v2rayN. Choose a package that matches the device and system architecture. For Windows, distinguish the desktop and classic WPF versions in the Windows download section. For macOS, choose a package for your chip in the macOS download section. For Linux, check both processor architecture and the package format supported by your distribution in the Linux download section. If the app reports a missing runtime, follow the package’s instructions; don’t piece together runtime files from another program’s folder.

For an archive that needs extraction, extract the entire package to a stable directory you have permission to manage, then run it from there. Don’t launch it from the archive preview window. If the app can write only some of its configuration files, it may close after starting or lose settings on the next launch. Check directory permissions, available disk space, and the actual security software logs first. On a managed device, ask an administrator to investigate if the system blocks execution; don’t change system-wide security settings as a test.

The UI is open but the core stopped: check the first error

When the core fails to start, the last log entry is often a generic shutdown message; the actual cause is usually earlier. If an address is already in use, check the local listening address and port for another client instance or a known service using it. Stop only processes you can identify and are allowed to stop, or switch to an available port and update related app settings. For a configuration parsing error, investigate the field or rule location named in the message rather than changing the system proxy first.

If the app exits only when you select one node, temporarily leave traffic interception off and retest with a node that worked before. If the first node fails and the second works, compare their transport settings, protocol fields, and related rules. If all nodes fail, check the shared configuration, file access, and whether the current client can invoke the core. If startup and the first connection work but the app exits after waking from sleep or changing networks, save the logs from around that time and note whether the network changed before the process exited.

Test in a clean environment, then migrate settings back

Before resetting, back up the configuration and working nodes, and note the UI settings and the system’s original connection method. Isolate the old configuration using a method supported by the client. In the new environment, import just one confirmed working node and test startup, shutdown, and a second startup. Once it runs reliably, migrate subscriptions and rules based on the old configuration in batches, testing after each step. If the issue returns after migrating a batch, narrow it down to that batch. Don’t overwrite the new configuration with the entire old one and repeat the same failure.

If the issue also occurs in the new environment, test starting the UI without connecting, then test connecting and immediately exiting. If the UI exits as soon as it starts, investigate its runtime environment and app data. If it fails only when intercepting network traffic, check the relevant permissions, core logs, and system network components. If only the old environment fails, preserve the part of the configuration needed to reproduce the issue; there’s no need to reset the entire device or delete other working settings. After changing the package, verify it by restarting the app and completing a full connection test.

08 · Mobile troubleshooting

Mobile disconnects: check VPN interception and background activity

On Android, three common issues are: the system session doesn’t start after tapping Connect, the connection drops when the app goes into the background or the screen locks, and the connection won’t recover after switching between Wi-Fi and mobile data. Test each issue separately; don’t lock the screen and switch networks at the same time. v2rayNG uses the Xray core, while v2flyNG is an alternative based on the V2Fly core. See the Android download section for packages and supported architectures. Before switching clients, check whether the issue is caused by system session management.

Can’t connect: check authorization, active sessions, and app scope

The first time an Android VPN connection is enabled, the system asks for authorization. If the app says it’s connecting but there’s no corresponding session in system settings, check the authorization prompt and client logs, then see whether another VPN is already using the current user’s VPN slot. On a managed device, an always-on VPN or work profile connection policy may be controlled by an administrator. Don’t force-disable managed settings. First identify the user or work profile running the app, then resolve any conflict according to system policy.

If the system session is active but only certain apps fail or take the wrong route, check the client’s per-app traffic list. Determine whether the list means “include only selected apps” or “exclude selected apps.” After changing it, reconnect and restart the affected app, then retest under the same user profile. A VPN icon in the status bar only confirms that a session exists; verify actual requests to check whether the app is included, the core can reach the node, and routing is correct.

Disconnects when locked: distinguish a stopped process from a dropped node

First keep the screen on, open pages continuously, and note the client status. Then lock the screen on the same network for a repeatable period. After unlocking, check the system session and client logs before reopening the original destination. If the session has disappeared, the process restarted, or startup log entries reappear, investigate system restrictions on background activity first. If the session is still active but requests time out, check for network changes, idle timeouts, or node issues. A notification still showing doesn’t prove the connection is working.

If the issue is related to background restrictions, adjust only this client’s battery usage or background activity settings, and only as allowed by the system. Settings names vary between devices. Note the original value before changing it, and don’t alter unrelated apps or system-wide battery settings. If data saver is also enabled, compare mobile data access in the foreground and background separately; don’t change battery and data restrictions at the same time. If the test doesn’t help, restore the original value and check for scheduled client restarts or network changes.

Switching networks fails: verify basic connectivity on the new network first

After switching from Wi-Fi to mobile data, the old connection may no longer work. The new one can’t be established until the system has a usable network path. First disable traffic interception in the personal client and test a destination that normally works on the new network. If the new network itself is unavailable, check network sign-in or mobile data settings. If direct access works, reconnect using the same node. If switching fails only in one direction, note the network types before and after the switch, reconnect time, and first error to distinguish a mobile network path issue from a client that failed to rebuild its connection.

Finally, retest three cases with the same app: foreground connection, recovery after locking the screen, and recovery after switching networks. Then test a second app to see whether the issue affects only one app. If the connection recovers automatically but takes time, record how long it takes from network availability to a successful request; don’t count the wait as a persistent disconnect. If only domain requests fail after switching networks, see the DNS section to check which resolver the app, system, and core actually use.

Back to symptom index ↑