Troubleshooting

V2Ray Troubleshooting Guide

First identify where the problem occurs, then adjust the relevant setting. If you haven't installed the client, imported a subscription and completed the initial checks, follow the Getting Started Guide in order. If the client has worked before and you're now seeing a specific issue, jump to the relevant section using this page's contents. The guide covers the normal setup; this page explains where things go wrong, how to verify the cause and how to roll back changes that don't help.

No internet after connecting

A connected status only confirms that the client completed a local startup step; it doesn't prove that web requests are using the right outbound route. First, split the symptoms into two cases: if websites still won't load after you quit the client, check the device's network or a leftover proxy. If they work after quitting but fail while the client is running, check the local inbound, routing and outbound settings. On desktop, the examples below use the recommended client, v2rayN; menu names may vary by version.

Restore a working baseline connection first

In v2rayN, use the tray menu to clear the system proxy set by the client, then quit the app. If your organization configured a proxy on the device, restore its original settings rather than turning everything off. On Android, disconnect in the client, then check the VPN status in system settings. If Always-on VPN or Block connections without VPN is enabled, losing internet after disconnecting may be expected. Don't change policies on a managed device yourself; ask your administrator to check them.

Use a browser to open two sites you can normally access that don't rely on the same service. Don't rely on an old tab: cached content can make a failing connection seem intermittent. If both sites fail on the basic network, check that you're on the right Wi-Fi network, complete any public Wi-Fi sign-in, and see whether another device on the same network works. If only one device fails, start with its proxy and network settings. If several devices fail, check the network connection itself.

Test the local listener separately from a real web request

On desktop, restart the core and make sure only one client instance is running. Open the settings and note the local SOCKS port. The example below uses the common port 10808; use the value shown in your client for the actual test. The second command explicitly sends the request through the local proxy, regardless of whether the browser uses the system proxy. It also lets the proxy resolve the domain, so you can check whether this path can load a web page end to end. It doesn't change system settings.

Test-NetConnection -ComputerName 127.0.0.1 -Port 10808
curl.exe --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.com/

If the first command reports that the port is unreachable, check whether the core started, whether it's listening on the loopback address and whether the port is correct. There's no need to keep switching nodes yet. If the first command succeeds but the second is immediately refused, check that the port uses the expected protocol: a local HTTP proxy and a SOCKS proxy aren't interchangeable, even if both are listening. If the second command gets response headers from the target site, this request made it through. That doesn't mean every site is reachable or that your browser uses the same local proxy.

Use logs to find where the request stops

Keep the log window visible, send one test request and note the time. If there's no connection entry at that time, first check which proxy the app is actually using, then make sure the log level records connections. If the request appears but doesn't use the expected outbound, check the active routing rules and whether a broad rule comes first. If the log shows the request going to the selected outbound, look at the first error about a timeout, name resolution or handshake. Don't mistake the final retry failure for the root cause.

Before you finish troubleshooting, restore any settings that were useful earlier, then retest a real-world scenario—for example, open a commonly used direct-access site and a test page that should use the proxy. If the explicit command works but your regular apps still can't load pages, go to System proxy not working. If only one service's domain fails, start with DNS issues; there's no need to reinstall the whole client.

Node timeouts and handshake failures

A timeout in a latency test can mean different things depending on how the client tests the connection. Some tests only try to connect to the target port; others visit a test site through the node. A successful port check doesn't prove the protocol handshake works, and a failed web test may simply mean the test site is unavailable. First, use the same node to make a regular web request. Match the log timestamp to the test, then decide whether to check the address, port or handshake settings.

Check the clock, node address and target port

Check the system date, time and time zone, and allow the device to sync with a trusted time source. Certificate validity depends on the system clock, so this is especially worth checking after a long sleep or manual clock change. If syncing clears the error, leave the correct time in place; there's no need to change protocol settings. If the log says the server domain can't be resolved, check that the full domain was imported, then compare system resolution with the resolution used by the client. Don't permanently replace the server name in a subscription with a temporary address just to test it.

For a TCP connection to a service you manage or are authorized to test, use Test-NetConnection on Windows to check the actual service port. An explicit connection refusal means you should check that the service is listening on the expected address and port, and that you're testing the right endpoint. A continuing timeout may point to the network path, access rules or an offline service. An open port proves only that the TCP connection succeeded; it doesn't verify the certificate, transport path or authentication. For UDP-based transports, don't treat this TCP test as conclusive.

Check the handshake fields against a single reproduction

Open the node details and compare them with the original parameters from the server: check the protocol, server port, transport and security type first, then the server name, host header and transport path. The server address is the connection destination. The TLS server name is used during the handshake and certificate identity check; the transport host header or path is used later to match the service. These values may be the same, but shouldn't be set identically by default. If a field isn't shown after import, don't fill it in based on guesswork—check the source configuration.

If the first log error reports a certificate name mismatch, an expired certificate or an untrusted chain, address that specific issue; don't disable certificate verification as a fix. If a read timeout appears before the TLS error, the delay may be in an upstream relay or the service response, not just the certificate. For errors related to core support, check the client selection in the Client Comparison, then see Xray and V2Fly Core Differences. Keep the original settings before switching cores, so you're not changing the node and core at the same time.

Cross-test to avoid mistaking correlation for cause

Keep the device and network the same, then test another node you've already verified. Next, keep the problem node and switch to another known-good network. If the same node fails on both networks, focus on its configuration or server status. If several nodes fail on just one network, focus on the network connection. Switching networks can also change the address family or DNS resolver, so these tests narrow things down but a single success doesn't prove the cause.

When reporting an issue to the service operator, include the time and time zone, transport type, whether the service port connection succeeded, and the earliest error in the log. Don't share authentication details, share links or screenshots showing subscription URLs. For more on error messages, see Common Log Errors Explained. To review the steps in the v2rayN interface, see How to Troubleshoot Node Timeouts in Order.

Subscription update failed or list is empty

Subscription updates have two steps: fetching the content and parsing the nodes. If the update fails, start by checking the network request. If it says the update completed but no nodes appear, check the selected group, response body and format. Keep any working group before you start; don't clear the list, and never send a personal subscription to an online conversion tool just to test it. Many subscription URLs grant access on their own, so a leaked URL should be treated like a leaked password.

Check which URL and group you're updating

In v2rayN, check the current group and its URL in the subscription group settings. After saving, make sure you update that group rather than checking a different one. On Android, verify the same details in the subscription group manager in v2rayNG or v2flyNG, then update from the node list. When copying a URL, watch for leading or trailing spaces, line breaks and punctuation added by chat apps. Query parameters are usually required; don't truncate or re-encode the URL by hand.

If the list still shows old entries, check for a keyword search, group filter or an option to show only the current group. Also distinguish between adding a group and updating one: adding only saves the URL; it doesn't confirm that the content was imported. If you create a temporary group for comparison, don't delete the original right away. First confirm that you can select and connect to a node in the new group, then deal with duplicates.

Choose the next step based on the fetch result

If the log shows a name resolution failure, connection timeout or certificate error, first fix the network path used to fetch the subscription. Check whether the client updates directly or through a proxy, and if it uses a proxy, make sure the existing node still works. If all nodes are down, updating through one of them can create a dependency loop. Use a network that can reach the subscription service, or ask the operator for a working endpoint. Repeating the same failed request won't help.

If you get an unauthorized or forbidden response, check whether the subscription expired or access was reset, and use the new URL provided by the operator. If the resource isn't found, check whether the path was changed. If requests are being rate-limited, wait as directed by the service. A success status can still return a sign-in page, maintenance page or error message. Check the response type only on a trusted device, and don't paste the body into a forum. If accessing the URL requires signing in on your device, a graphical client usually can't reuse your browser's login session.

Verify the response format and node compatibility

Distinguish between a single node share link, a node-list subscription and a full core configuration. Each has a different import method; pasting a full configuration into a subscription URL field won't produce a usable list. Some services return different formats depending on the requesting client. Being able to download text from the same URL in a browser doesn't mean your current client can parse it. Ask the source which client format the URL provides rather than manually editing an encoded block of text. If only some entries appear, note which protocols or transports are missing and check the fields supported by the available core.

After an update, check that the expected nodes appear in the target group, then select one and make a web request. Seeing a list means the response was parsed; it doesn't guarantee that every node works. Likewise, a working old node doesn't prove the subscription updated. If you keep getting old content, note the update result shown in the client and check whether the server is caching it or the new version hasn't been published yet. Once you've confirmed what's changed, organize the groups. If you just can't find the right menu, follow the import steps in the Getting Started Guide.

Slow speeds and intermittent stuttering

First pin down what “slow” means: does the first page load take a long time, is download throughput consistently low once it starts, or does live audio or video stutter every so often? These can point to DNS or connection setup, sustained transfer, jitter or packet loss. A single latency reading reflects one response time, not large-file speed. And a fast speed-test site doesn't prove that a work service performs just as well over the same route.

Set up a repeatable comparison

Pause sync, backups and other downloads. Choose the same publicly accessible test resource, then compare the basic network and proxy routes at roughly the same time. Repeat the test several times with resources of similar size and compare typical results, not just the fastest one. If the two routes can't reach the same site, compare each against a reachable baseline rather than treating them as a strict same-target test. Record initial page-load delay, sustained transfer and interruptions separately to distinguish symptoms that might otherwise seem alike.

Keep the node the same and test on two types of connection, such as Wi-Fi, Ethernet or mobile data. Then keep the network the same and compare different working nodes. If both the basic network and proxy are slow, check signal strength, background traffic or the access link first. If one node is consistently slow under the same conditions, ask the service provider about bandwidth limits or load. If it happens only at certain times, test at another time too; don't mistake occasional evening congestion for a persistent settings problem.

Make sure traffic is using the route you're testing

Have the client log one real request and check the target domain and outbound tag. An app may bypass the proxy based on its own settings, or match a catch-all rule in the current routing config, so it might not use the route you intended to test. Some system proxy entry points mainly handle HTTP or HTTPS requests; don't assume that an app's UDP traffic takes the same route. Check the documentation and logs to see whether the app supports the current connection method before blaming a protocol difference for the stutter.

Web pages load scripts, images and API requests from multiple domains. If the main document loads quickly but the page remains unusable, check the browser's Network panel for the slowest request. Identify whether the delay is in DNS lookup, connection setup or content download, then compare it with the client logs. If only one resource domain is consistently slow, focus on its routing and destination service; don't reset all routing rules for a single resource. If you raise the log level to debug, leave it on only while reproducing the issue, then restore the normal level.

Check device load and side effects of changed settings

While speeds are low, check Task Manager or Resource Monitor. If the processor stays busy during downloads, the device heats up or disk writes become a bottleneck, stop high-load apps and retest once the device has cooled. Comparing a browser test on its own with one run alongside other tasks can reveal a local bottleneck more clearly than watching the download window alone. If Android only becomes unstable with the screen off, follow Android background disconnects to check whether the system is stopping the service.

Don't change the transport, enable multiplexing and adjust virtual interface settings all at once without evidence. Small pages working while large transfers keep stalling doesn't, on its own, prove a packet-size problem. First rule out rate limits at the destination and packet loss; if needed, ask the network administrator to inspect the path. Keep a change only if the same test repeatedly improves and it doesn't introduce new timeouts, audio/video issues or local network problems. Otherwise, undo it and continue troubleshooting with the comparison results.

DNS resolution and routing issues

A resolution error can affect two different domains: failing to resolve the server domain can prevent the client from establishing an outbound connection, while failing to resolve a website domain may affect only a few requests. Use the log to identify which domain triggered the error, then check whether the system, app or core performed the lookup. A browser's “server not found” message doesn't automatically mean system DNS is broken; the error may occur after the request reaches a proxy.

Compare system lookups with actual app requests

Use the system's default settings to look up a public domain, then note the returned address, error or wait time. On Windows, you can use the built-in diagnostic tool below. To test a specific domain, replace the example with a public, testable target. This only shows the result of that lookup; it doesn't mean the browser's secure DNS, the resolver in the core config or the proxy's remote end got the same answer.

Resolve-DnsName -Name example.com -Type A -DnsOnly
Resolve-DnsName -Name example.com -Type AAAA -DnsOnly

Querying IPv4 and IPv6 separately helps identify which type of result is available; not every domain needs to return both. Getting an address record doesn't mean your network can connect to it. If a system lookup succeeds but the browser fails, check whether the browser uses its own secure DNS and compare with another app using the default network settings. If only an explicit proxy request fails, check whether the core or remote end resolves the target, then review the logs for that route. Restore the original secure DNS policy after the comparison.

Understand the order of domain and IP matching

When the core receives a domain name, it can choose an outbound using domain rules. Whether it then resolves the domain to an IP address for matching depends on the routing domain strategy. AsIs doesn't actively resolve domains for route matching. IPIfNonMatch can try resolving a domain to match IP rules if no domain rule matches the request. If the app already resolved the name and passes only the destination IP to the core, a domain rule may not match. Check the target shown in the log before deciding which rules to review.

The following core configuration snippet assumes an outbound tag named direct and shows only a rule that sends one locally managed domain through the direct outbound. For your own config, replace it with a domain you manage and merge the rule into your existing rules. This isn't a full configuration and won't assign a resolver automatically. If the domain is resolvable only on your private network, a correct direct rule still won't make a public resolver return a usable address.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:router.home.arpa"],
        "outboundTag": "direct"
      }
    ]
  }
}

Handle internal domains, caching and startup dependencies

Domains used for home network administration or internal company services should continue to use a resolver trusted by the relevant network. Don't send internal names to a public resolver just to test them. After changing a rule, record the old and new results, then restart the test app to rule out a reused connection. Cached records have a time to live, and the system, app and core may refresh at different times. If results alternate, first find out which layer returned each record instead of switching resolvers repeatedly.

Another common issue is a dependency loop: the node address relies on a domain lookup, but the request used to resolve it is configured to go through that same node before it can connect. Even a correctly defined proxy outbound can't start in this situation. Check the initial resolution path for the node domain, then check the policy for target domains. After fixing it, test node startup, a regular website and any internal names that need to keep working. See Quick Reference for parameter definitions; don't override existing internal network settings with a single new rule.

System proxy not working

The system proxy determines where apps that follow system settings send requests. Routing determines which outbound the core uses after it receives them. Test these separately. A web request routed directly doesn't mean it bypassed the local client. Conversely, a client status bar saying the proxy is set doesn't guarantee every app reads system settings. To identify which layer is at fault, first check whether a real request reaches the local listener.

Check the actual entry point on desktop

In the v2rayN tray menu, select the option to configure the system proxy automatically, then check the result in system network settings. For apps that need a manually configured proxy, enter the listening address and port shown in the client, using a protocol the app supports. Don't use the remote node's port as the local endpoint. When testing on the same computer, use the loopback address; there's no need to enable “Allow connections from LAN” for troubleshooting. If you've changed the local port, check that manually configured apps aren't still pointing to the old one.

SystemWhere to checkHow to verify
WindowsSettings → Network & Internet → ProxyCheck manual proxy settings and the setup script; some services use proxy settings different from desktop apps.
macOSSystem Settings → Network → Current Service → Details → ProxiesMake sure you're viewing the network service in use, then check the selected proxy type and port.
LinuxDesktop network proxy settings, the target app's preferences or its launch environmentCheck whether the desktop session and command-line process use the same entry point; they may not share proxy settings.

If the system page shows both a setup script and manual settings, record the original values and check whether they're managed by your organization. An old script may send requests for certain domains directly. Another network tool may also overwrite the proxy after the client sets it. If a proxy pointing to a local port remains after you quit the app, use the client's clear-system-proxy option to restore it. On a managed device, restore the original settings provided by your administrator; don't delete management entries with an unknown source.

Distinguish app overrides from routing results

If the problem continues, test one app on its own. Check whether it uses the system proxy, has a separate proxy setting or has a direct-connection override. Close existing test tabs and make a new request; restart the app if needed so an existing connection can't keep using old settings. Command-line tools may get a proxy address from environment variables. An explicitly successful request through the local proxy proves only that invocation works; it doesn't verify the system proxy settings.

If the client has received the request, check the selected outbound in the logs. A direct tag means the request reached the core and was sent directly by a routing rule, so check routing rather than continuing to change the system proxy. Check whether a broad rule earlier in the list catches the request before a more specific one, and whether it ultimately matches the default outbound. If you specifically want to test virtual interface mode, record the current system proxy and other network tools first, then test them separately. Avoid having two entry points active at once, which makes the results hard to interpret.

Check what happens after quitting, restarting and changing networks

Once fixed, verify the handoff in two stages: while the client is running, confirm the system settings match the active listener; after quitting, confirm apps return to their original proxy state. Then switch between your usual networks and check whether the system uses a different network service or reloads an old script. If another app overwrites the setting every time the device restarts, find out which app is writing it instead of configuring the same port in multiple tools. If only one app still doesn't work, check its proxy setup in the FAQ.

Client crashes and startup failures

First identify when startup fails. If the app quits before a window appears, check the package type, dependencies and directory permissions. If the window opens but the core fails to start, check the logs, listening ports and current configuration. If the app is still running but its window disappeared, check whether it was minimized to the system tray. These cases need different fixes. Don't overwrite the old files after the first crash; preserve them so you can investigate or restore them.

Check that the package matches your system

On desktop, revisit the download page and check the operating system, processor architecture and package type. The Windows desktop and classic WPF editions have different interfaces, and runtime requirements depend on the package; if an error specifically says a .NET runtime is missing, check the required runtime type and architecture. The .NET Desktop Runtime and .NET Runtime are different components. For an archive, extract all files to a directory your user account can read and write before launching the executable. Don't run it directly from the archive preview.

On macOS, check the chip type and package architecture. Read the system message carefully to see whether it's about an unidentified developer, an architecture mismatch or insufficient permissions. On Linux, check that the package format and architecture suit your distribution, then address missing dependencies reported by the package manager. Don't disable system protection globally or run as administrator indefinitely just to get past an error. If the error points to an unwritable directory, use a normal user data path instead of granting unnecessary permissions to the entire app directory.

Distinguish a core exit from a port conflict or configuration error

If the window still works, find the first error about starting the local core in the client log. If the address is already in use, check whether an old instance is still running or another legitimate service is using the port. On Windows, use the command below with the actual port to find the listening process ID, then look it up in Task Manager. Don't terminate a process you don't recognize. You can choose an unused port for the client, then update any proxy settings that depend on that entry point.

Get-NetTCPConnection -LocalPort 10808 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

If the log says the core file can't be read, check that extraction completed, the file exists at that path and the system security history has no related alert. If it reports an unknown field, invalid outbound or configuration parse error, switch back to a previously working node and default routing first. The reported field may come from a configuration generated by the client. In that case, changing the source setting in the graphical interface is more effective than editing a file that gets overwritten on every startup.

Preserve your data and reproduce the issue in a separate environment

If you suspect corrupted user settings, quit the client and any leftover core processes, then back up the data directory the app actually uses. Store the backup somewhere only you can access. If the app explicitly supports starting with a new directory and isolated data, compare with an empty config. Otherwise, check the documented data path first; changing the program directory alone doesn't isolate the data. If the app starts with an empty config, restore one subscription or known-good node first, then restore routing and interface settings one at a time.

If it still fails with an empty config, note the operating system and architecture, package type, whether the client window appeared, and any matching faulting module in the local event log. The absence of a log directory doesn't mean there was no error; the crash may happen before logging starts. On Android, clearing app data removes local settings, so consider it only after making a backup and confirming you can import them again. For desktop cases, see v2rayN Startup Crashes: Runtime and Permissions Troubleshooting.

Android permissions, per-app proxy and background disconnects

On Android, troubleshoot based on when the connection drops. If connecting fails immediately, check system authorization and existing VPNs. If only one app can't connect, check the per-app list and mode. If the connection drops after the screen has been off for a while, check background and battery settings. Test the same node in three conditions—foreground, screen off and after switching networks—to distinguish a core timeout from the system stopping the service or an app not being included in the VPN.

Check VpnService authorization and VPN conflicts

The first time v2rayNG starts in VPN mode, Android shows a connection request. Make sure it names the client you intend to use before granting permission. If tapping Connect doesn't show a prompt, authorization may already be in place, or an existing VPN or device management policy may be preventing a new connection. Check the current VPN provider in system settings. Usually, only one VPN can be active in the same user profile or work profile. When another network app takes over, Android may revoke the previous VPN.

Always-on VPN and Block connections without VPN are separate settings with different effects. The first controls whether the system maintains or tries to reconnect the VPN; the second may block regular network requests when the VPN disconnects. Before testing the basic network, check whether either is enabled. Don't mistake a policy taking effect for a broken Wi-Fi connection. Settings on work profiles and managed devices may be locked; ask an administrator for help rather than disabling protection as a permanent fix.

Understand the per-app list

Open the client's per-app proxy settings and check whether the list means “only selected apps use the VPN” or “selected apps bypass the VPN.” In bypass mode, the same checkmark may mean the opposite. For testing, choose two easy-to-distinguish apps: one that should use the VPN and one that should use the regular network. Save, reconnect the VPN and make a new request in each app. Refreshing an existing page may reuse an old connection, so open a new page or restart the app you're testing.

If an app was recently reinstalled, installed in a work profile or created with a system cloning feature, an entry with the same name may not be the instance you're testing. Check its icon, profile and the app entry shown in the client. A sign-in page may also open in the system browser or another component, so the original app may not be making the request. Identify which app is sending the request before changing the list. Don't route every app through the same outbound indefinitely just to get one app working.

Use screen-lock and network-switch tests to locate background drops

Connect while the app is in the foreground and confirm it works, then lock the screen for long enough to reproduce the issue. After unlocking, don't reconnect immediately. First check the VPN indicator, persistent notification and client logs. If the service has stopped and there are no corresponding node errors, check whether the system restricted background activity. If the service is still running but the logs show reconnection attempts or DNS timeouts, check whether the network changed during sleep. You can switch the same node once between Wi-Fi and mobile data to see whether the old connection recovers properly after a network change.

If you confirm a background restriction, open the app's system settings and look for battery or background usage options. For the client you use, try allowing background activity or selecting “Unrestricted.” Some devices have additional settings for auto-start or background activity; names vary, so check the device documentation. Change one setting at a time and repeat the same screen-off test, noting any improvement and battery impact. The same checks apply to v2flyNG; use the labels shown on your device. For more details, see Android Permissions, Battery Optimization and Per-App Proxy Settings.