V2Ray Troubleshooting

No internet access

“Client started” only means the graphical interface is running. It does not confirm that the core is running, a server connection is established, or apps are using the proxy. Start by separating three cases: the internet is unavailable even with the proxy off; it stops working only when the proxy is on; or only a particular app or website has a problem. Each case calls for different checks. Switching protocols or reinstalling repeatedly rarely narrows down the cause and may overwrite a working configuration.

Check basic connectivity and identify the scope

In the v2rayN tray menu, clear the system proxy, then exit the client and open a website that normally works without a proxy. Confirm that Wi-Fi is connected, the gateway is reachable, and any public Wi-Fi sign-in is complete. If you still cannot get online, troubleshoot the system network, router, or upstream connection first. On Android, stop the VPN and test Wi-Fi and mobile data before treating a basic connectivity problem as a failed subscription.

Once basic connectivity is confirmed, restart the client and test with a single active server. Do not run two proxy clients at once or combine the desktop system proxy with another tool's virtual network adapter. Multiple entry points can send requests along different paths, causing symptoms such as a browser working while other apps time out—or the whole system recovering as soon as one program exits.

Check the core, local listener, and app proxy settings

Open the client log. First check whether the core started successfully, then look for new entries when you try to access a site. If the log shows a configuration parse error, a failed bind, or a port already in use, fix the local startup issue first; testing a remote server will not help yet. If the core is running but no related log entries appear when you open a page, check whether the app uses the system proxy or has its own proxy settings, and verify that its port matches the active listener.

The Windows example below specifies a local HTTP proxy to rule out browser settings. It uses port 10808; before running it, check which HTTP or mixed-protocol listener port is actually enabled in the settings. If the port accepts SOCKS only, use the corresponding protocol instead. The destination is a standard example domain and may not be reachable on every network.

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

If the local address cannot be reached, check whether a listener is active. If the local proxy connects but the remote request times out, follow the server timeout troubleshooting steps. An HTTP response from the destination—even an access-denied response or a rejection of the requested method—means that request reached a responding endpoint, but it does not prove that every site or protocol is working. Do not judge the entire connection path by the command's exit code alone.

Separate routing problems from connection problems

If the local proxy test gets a response but the browser cannot access the site, check browser proxy extensions, the system proxy, and network filtering by security software. If only certain domains fail, check whether their rules send them direct or through the proxy, then investigate DNS. You can temporarily use an explicit proxy route as a comparison, but restore the original rules afterward. Do not change DNS, routing, and server settings all at once, or you will not know which change made a difference.

Finish with a full check: direct access works, the local proxy responds, the browser uses it as expected, and the target domain takes the intended route. Note which layer fails, then continue to the relevant section. If a specific site reports an account restriction, regional restriction, or service error, address the message returned by that site. That is different from the client being unable to connect at all, and repeatedly changing settings will not fix the underlying cause.

Server connection timed out

A timeout means a step did not finish within the allowed time; it does not necessarily mean the server is offline. The client may be waiting for DNS resolution, a TCP connection, a secure handshake, or a response from the test destination. Save the logs for the same time period, find the earliest error, and then review any follow-on errors. A generic timeout at the end is often just the result; an earlier DNS or handshake error is more useful for diagnosis.

Identify the test type and failure stage

Tcping generally checks whether a TCP connection can be made to a server address and port. It does not fully verify credentials, transport settings, or access to a destination website. A real connection latency test sends a request to a test address through the proxy, so its result also depends on that destination. That's why Tcping can succeed while a webpage fails. Likewise, a server not responding to ordinary ICMP requests does not prove that the proxy is unusable.

First confirm that the server entry still comes from the current subscription, rather than an older standalone copy. Check that the address, port, and protocol are complete, and make sure you have not selected a similarly named entry from a different group. If server settings changed recently, update the subscription or recreate the entry with all the correct parameters; changing only the address while keeping outdated transport settings may not work. For more on test limitations, see how latency tests work.

Check settings based on the log message

When using TLS, the server address and the name used for the handshake may be different. Do not copy the address field into every name field without checking. Verify the system date, time, and time zone, since clock drift can affect certificate validity checks. For certificate errors, check where the configuration came from and verify the server certificate instead of enabling certificate verification bypass. Bypassing it may seem to restore the connection while leaving incorrect identity settings in place.

When using REALITY, check the server's required public key, short ID, server name, and related flow settings together. Whitespace, incomplete copies, or parameters from a different server can cause the handshake to fail even when the underlying port is reachable. Which fields are required depends on the server configuration; do not fill them in based on other entries. See REALITY terminology for background.

Narrow down network issues with controlled comparisons

If the same entry fails on Wi-Fi but works on mobile data, compare network paths, DNS results, and gateway policies before reinstalling the client. Keep the server, protocol, and destination the same across tests. Reconnect after switching networks so an existing connection does not continue using the old path. If all entries fail at once, also check whether a recent firewall update changed the app's rules.

If one server keeps failing while others in the same group work, the issue is more likely specific to that entry or server. After confirming the subscription is up to date, send the configuration provider the time of the error, the failure stage, and a redacted log. Never share the full subscription URL or expose credentials. If you need to compare core capabilities, read the core selection guide; switching cores is not a universal fix for timeouts.

Increasing the timeout can help confirm a slow response, but it cannot fix an incorrect address, a port with no listener, or mismatched handshake settings. After each change, test against the same destination and keep the original result for comparison. If the log shows that the proxy connection is established but the test site does not respond, verify with another known-good destination rather than assuming the whole server is down.

Subscription update failed

A subscription update involves downloading content, parsing its format, and writing entries to a group. An update error may mean the URL is unreachable, or that content downloaded but turned out to be a login page, an error page, or an unsupported configuration format. Keep your existing entries for now; do not delete the whole group. If its servers still work, deleting them may leave you without a usable connection for further troubleshooting.

Check the URL and group settings

Open the subscription group settings and make sure the URL is a complete, single-line link. Do not include explanatory text, quotation marks, line breaks, or trailing spaces. Subscription URLs often contain personal access credentials and should be treated like passwords; do not include them in public screenshots or paste them into online conversion tools. Check only that the structure is complete—never send the original URL to someone for review. If you need help, describe the response status and error type instead.

Make sure you are updating the same group you are viewing. Groups with identical names can make it look like an update made no difference. Rename them to distinguish their purpose, then update them one at a time. If the client has an enable switch, update URL, or filter options, confirm that the group is enabled and that its filters are not excluding every entry. An empty group does not necessarily mean the network request failed.

Try updating directly and through the proxy separately

Some subscription URLs are reachable over the current direct connection; others require an existing proxy connection. Test each update method provided by the client, changing only the request path between tests. Before trying an update through the proxy, make sure at least one server works. If the existing proxy is already down, relying on it to update the subscription can create a recovery loop.

If the URL opens in a browser but the client still fails, do not assume the client is at fault. The browser may have a login cookie, use its own proxy, or follow an authenticated redirect; client requests usually do not inherit those states. Confirm that the provider explicitly offers the URL as a client subscription endpoint. A webpage that requires interactive sign-in is not the same as a subscription response the client can read.

If a response status is available, an authentication failure usually means you need a new, valid URL. If requests are being made too frequently, stop refreshing and try again later as directed by the provider. Assess server errors alongside other requests made around the same time. Do not attribute every status to an outdated client, and avoid repeated retries through browser extensions, which may trigger further access restrictions.

Confirm the format and import result

Common subscription content includes one share link per line, an encoded collection of links, and native JSON for a specific core. A file extension or URL suffix does not guarantee the content is valid, and a subscription endpoint may return different content depending on the request. If you receive a native configuration, use the client's configuration import option rather than assuming every JSON file can be updated as a regular subscription group. See subscription formats and conversion for details.

If the update reports success but no servers appear, switch to “All” or clear the list search first. Then check subscription filters, supported protocols, and any parsing messages in the log. A single-server share link and a subscription URL that can be refreshed are different resources. The former is for importing one entry and should not be used as a subscription URL just because it looks like a link. See share links vs. subscription URLs for details.

If the URL has expired or the provider replaced it, update the URL in the existing group, run the update again, and check whether the entries change. If you create a new group for comparison, keep the old one until the new entries pass a connection test. This prevents confusion from two groups updating at the same time. Once resolved, remove temporary filters and duplicate groups, restore a reasonable update frequency, and keep a private backup of the latest working configuration.

Connected, but slow

First describe exactly what is slow: a webpage takes a long time to open, a file downloads slowly throughout, video playback stutters, or just one app responds slowly. Initial loading involves DNS, connection setup, and the handshake; sustained transfers depend more on bandwidth, packet loss, congestion, and server load. Comparing these different symptoms can lead to the false conclusion that low latency always means fast downloads—or that a site's own speed limit is caused by the client.

Set up a reproducible comparison

For each test, keep the device, network, server, and destination site the same, and pause system updates, cloud sync, and other high-bandwidth tasks. If Wi-Fi is weak or the band is congested, move closer to the router or compare using a wired connection. If similar resources are also slow without the proxy, troubleshoot the local network first. If they slow down only through the proxy, investigate the proxy path. Results from different dates or resources are not directly comparable.

Do not run download speed tests against every server at once. Concurrent tests compete for local bandwidth, add load to the servers, and can make stable connections look inconsistent. Test a small number of candidates one at a time, in the same order, leaving time between tests for conditions to settle. Record the start time, network type, and resource source; a momentary peak is not a reliable measure of sustained performance.

Measure connection setup and sustained transfers separately

If every webpage is slow to open initially but images and files load normally afterward, focus on DNS, handshakes, connection reuse, and routing rules. If loading starts quickly but downloads slow over time, compare Wi-Fi stability, long-lived connection quality, and remote speed limits. Browser developer tools can help identify waiting time, but caching, site scripts, and third-party resources affect results. Start with a simple page as a baseline.

Tcping measures an early-stage connection characteristic; real connection latency includes more of the proxy path, while a download test applies sustained traffic. These tests are not interchangeable. A server with higher measured latency may sustain throughput more consistently; one that connects quickly may still slow down during busy periods. Choose based on your actual needs, not by sorting on a single metric.

Check split routing, duplicate capture, and transport settings

If only some resources are slow, check whether the main page and its images or video use different routes. A webpage may connect to several domains, some through the proxy and others directly; a connected status does not mean the entire page uses the same exit. A temporary consistent route can help isolate the issue. Once identified, correct the rule order rather than relying on a temporary rule that overrides all traffic.

If the system proxy and virtual network adapter are both active, make sure the core's own outbound traffic is not sent through the proxy again. Duplicate capture, an incorrect upstream proxy, or a chained setup can add round trips or even create a loop. Do not enable every mode at once for a speed test. For a standard browser test, start with one clearly defined entry point. Test virtual adapter mode separately only if you need to support apps that do not follow the system proxy.

Transport settings must match the server configuration. Enabling multiplexing, changing the transport protocol, or copying someone else's connection settings will not automatically increase bandwidth and may cause compatibility issues. If you suspect an issue with packet size along the path, test gradually based on the specific symptoms and network. Keep the original values and change one setting at a time; do not copy an entire set of generic network “optimizations” without evidence.

Finally, distinguish what you can change from external limitations. The client can correct routing, DNS, and traffic capture settings, but cannot guarantee that server load, destination site policies, or the upstream network will remain constant. If repeated tests under fixed conditions point to the same remote path, share the time period and symptoms with the configuration provider. Restore temporary test settings and check stability with your everyday apps instead of running speed tests continuously.

DNS and domain resolution

DNS issues often appear as domains that will not load, an intermittent service, or a resolution error in the log before a connection starts. Distinguish resolution of the server hostname from resolution of the destination website's hostname: the first lets the client find the proxy server; the second determines how the request reaches its destination. They may use different resolvers and routes, so changing one system DNS setting does not necessarily affect every step.

Identify where resolution takes place

If the server address is a hostname, it must resolve to a usable address before the connection can be established. If the resolution path itself depends on an active proxy, this can create a startup dependency loop. First confirm that the basic network can resolve the server hostname, then check the bootstrap path in the client DNS settings. Do not replace the hostname with an address you found elsewhere without checking: the server may use a dynamic address or require the correct handshake name.

The app, local system, or proxy core may resolve a destination hostname, depending on the app's proxy protocol and client settings. SOCKS can also resolve names locally or leave resolution to the proxy, so a browser working does not mean a command-line tool is doing the same thing. Record whether the test uses an HTTP proxy, SOCKS proxy, or virtual network adapter, then use the log to determine where the hostname is translated into an address.

System commands can check whether basic system DNS returns a result, but they do not confirm the core's final DNS result. The command below uses an example domain; for a real issue, replace it with the public domain that is failing. Do not paste a full link containing account details or access credentials into a command. Also check whether the results include different address families.

nslookup example.com

Check encrypted DNS, address families, and cache

A browser's secure DNS setting may bypass the system resolver, and the client may have its own encrypted DNS configuration. To create a comparable test path, temporarily make the browser follow system settings and see whether the issue changes. Restore the setting afterward based on your needs. Resolver reachability and the suitability of its returned address are separate issues; if the server does not respond, repeatedly changing DNS providers may not fix the routing problem.

Some domains return both IPv4 and IPv6 addresses, but the current network may not reach both address families equally well. If the log shows repeated attempts over an unreachable address family, compare the system network status with the client's DNS strategy. Temporarily limiting the address family can help with diagnosis, but permanently disabling one protocol is not a universal solution. Choose settings that match the available network and server capabilities.

After changing DNS settings, old results may remain cached by the browser, system, or core. Close old tabs or restart the relevant apps, restart the client if needed, then test the same domain again. Windows can clear the system DNS cache with the command below, but that will not clear every app's cache or fix an incorrect upstream resolver. Do not keep flushing caches instead of checking the failing path.

ipconfig /flushdns

Keep DNS and routing paths aligned

Direct and proxied traffic may need different DNS paths. If a direct request gets an address that only works from another network exit, the connection may fail or slow down. If a remote DNS request is routed through an unreachable exit, it may time out. First check how DNS requests themselves are routed, then check domain matching rules. Do not focus only on the returned address while ignoring how the query was made.

In virtual network adapter mode, also check that system DNS follows the capture path expected by the client and that another VPN is not rewriting the same setting. If you use a feature such as virtual address mapping, make sure DNS and subsequent connections are handled by their corresponding rules; copying only one part of the setup is not enough. For standard subscription imports, start with the client's graphical settings rather than editing automatically generated runtime configuration.

After a fix, verify at least three things: the server hostname resolves, the destination hostname gets a response, and actual traffic follows the expected route. If only one domain remains affected, compare its authoritative DNS changes, site status, and results from different networks before adding a dedicated rule. DNS is not a master switch for every connection issue; even successful resolution can be followed by port, handshake, or destination service failures.

System proxy not working

The system proxy is a set of proxy settings that the operating system makes available to apps. It does not force all traffic through a proxy. Browsers usually follow these settings, but some command-line tools, games, and apps with their own networking modules do not. If the browser works but one app does not, check how that app connects instead of switching to global routing and waiting; routing can only handle requests that have reached the client.

Match the listener to the system proxy settings

In v2rayN's settings, check the local listener address, port, and supported proxy protocols, then compare them with the system proxy settings. Different configurations may use different ports; do not assume a tutorial's example is the right value for your device. Local apps typically connect to a loopback address. Pointing them to another device or using the remote server's port can leave the system proxy enabled but unable to reach the local listener.

The Windows PowerShell command below checks whether a TCP listener is active on the example port. If there is no output, first confirm that the client core has started and that the port matches the current settings. If there is output, check which process owns the port. A listener only proves that a program is using the port; it does not prove that it is the intended proxy or that the remote server is reachable.

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

If another program is using the port, close it once you have confirmed its purpose, or change the client's listener port and update the app's proxy settings to match. Do not change the client while leaving the old system proxy port in place. Also, do not expand the listener address to all network interfaces just to allow access from the same device. Allowing LAN connections changes the access boundary and is unrelated to fixing the local system proxy.

Distinguish manual proxy, auto-configuration, and app-specific settings

Manual proxy settings and automatic configuration scripts work differently, and the system interface may retain fields for both. A client mode name does not necessarily correspond to a single operating system switch; check the actual address, port, or script URL it sets. After changing modes, close and reopen the test app so an old process does not keep using an existing direct connection and make the settings appear ineffective.

Browser extensions, enterprise policies, and app-specific proxy options can override system settings. Temporarily disable proxy extensions to compare, then check whether the app is set to “no proxy” or to a different fixed address. Some command-line programs read environment variables instead of the desktop system proxy, while other Windows components use separate proxy settings. A single tray switch cannot be expected to update every environment.

Check for stale settings and virtual network adapter capture

After an unexpected client exit, the system proxy may still point to a local address that is no longer listening. This can make every webpage stop working when the client exits. Temporarily turn off the stale proxy in system settings, confirm direct access works, then restart the client and configure it again. Do not start by deleting network adapters or resetting the entire system network; a stale address does not require destructive troubleshooting.

If you need to capture traffic from apps that do not use the system proxy, check the client documentation to see whether virtual network adapter mode is appropriate. It may require permissions and can take over routing and DNS. First confirm that the regular local proxy works, then test the adapter mode separately. Elevated permissions are not a fix for every system proxy issue; grant them only when there is a clear permission error or a specific capture requirement.

Final verification should cover both settings and traffic: the system interface shows the correct address, the client port is listening, app requests appear in the log, and the destination works as expected. A checked item in the tray menu does not prove all four. Afterward, exit the client and check that the system returns to the expected state to prevent the same issue from recurring before the next launch.

Client crashes or won't start

First distinguish between a graphical interface that will not open, an interface that opens but whose core exits, and a program that closes after running for a while. These involve different layers: the graphical runtime, generated configuration or core process, and system resources or background software. Note what triggers the issue—immediate exit at startup, a crash after a subscription update, or failure when enabling the virtual network adapter—and check the logs for that time. “It doesn't work” is not enough to diagnose the cause.

Check the package type, permissions, and runtime first

Choose the appropriate package for your operating system and processor from the client downloads page. The Windows desktop and classic WPF editions use different UI technologies, so check the requirements shown for the specific package rather than assuming they all need the same runtime. On macOS, distinguish Apple Silicon from Intel. On Linux, check both processor architecture and distribution package format so a mismatch is not mistaken for a damaged configuration.

If the download needs to be extracted, extract all files to a location where you have write access before running it. Do not launch the app from the archive preview window. Make sure the required files are in the expected directory and that a cleanup tool has not moved the working directory. If the system's security controls block installation or the first launch, check the specific reason they provide and use the system's app authorization process. Do not disable all device protection.

If the system reports a missing runtime, check the system architecture and required components shown in the message. If file access fails, check folder permissions, available disk space, and whether another program has locked the configuration file. Cloud-sync folders can cause file locks or sync conflicts. For testing, copy the app to a normal local folder, keep the original in place, and do not run two instances that write to the same configuration.

Separate interface problems from core configuration errors

If the interface remains open but the core keeps exiting, check whether the log reports an unsupported field, invalid protocol combination, port conflict, or missing rule file. If you recently enabled a custom configuration, routing rule, or DNS setting, revert that change first. Users with standard subscriptions should avoid editing automatically generated runtime configuration: the client may overwrite it next time settings are applied, and the interface can end up out of sync with the actual configuration.

If you are specifically checking native JSON syntax, the example below is valid minimal JSON. It illustrates objects, arrays, commas, and boolean values; it is not a complete core configuration that can establish a proxy connection. Watch for trailing commas, Chinese punctuation, and quotation marks in strings. Valid JSON syntax does not guarantee that its protocol fields are supported by the current core.

{
  "log": {
    "loglevel": "warning"
  }
}

For core compatibility issues, first confirm the protocol capabilities required by the entry, then compare them with the core the client actually uses. v2rayNG and v2flyNG use different core families; changing the app name does not make their settings automatically compatible. See Xray and V2Fly core differences for background. Do not overwrite files in the client directory with cores from untrusted sources.

Test with an isolated configuration

If you suspect a damaged user configuration, exit all instances and back up your settings, subscription groups, and custom rules. Then use the method supported by the client to test with a new user configuration directory. Do not delete the original directory. If the new configuration starts, the issue is more likely in the old configuration or an extension setting. Restore subscriptions, routing, and other settings in batches, checking which step brings the issue back instead of copying everything over at once.

If the client still exits consistently with a clean configuration, check system event logs, available storage, memory pressure, and security software blocks. On Linux, also check the graphical session and package dependencies; on macOS, look for system authorization prompts. Gather evidence that matches the trigger before deciding to update or reinstall. An in-place reinstall may not remove a damaged user configuration, so continued failure after reinstalling does not automatically mean the software itself is at fault.

Once the client runs again, test a known-good configuration with a standard proxy before restoring advanced features one at a time. Reproducible steps, the exact error, and checks already ruled out are more useful for diagnosis than repeatedly trying different packages. For first-time installation, see desktop installation and initial setup. This chapter focuses on troubleshooting, not routine installation.

Android connection and background operation

On Android, start by troubleshooting common connection issues with v2rayNG. Consider v2flyNG when you need V2Fly core capabilities. With either app, distinguish the server configuration from the system VPN tunnel: a VPN icon in the status bar only confirms that the system tunnel is up, not that the server handshake succeeded. If the icon is present but access still fails, check local traffic capture, server connection, routing, and DNS in that order.

Check VPN permission and network status

The first time you connect, Android asks you to approve VPN access. If you denied the request, start a new connection and follow the system prompt. Devices restricted by a work profile or device management policy must follow those policies. Do not repeatedly clear app data to work around an authorization problem; that also deletes subscriptions and custom settings. Disable other VPN apps first and confirm that another VPN tunnel has not replaced the current one.

Public Wi-Fi may require sign-in through a captive portal. Stop the VPN and complete network sign-in before reconnecting. After switching from Wi-Fi to mobile data, an old connection may remain stuck until it times out; stop and reconnect, then check whether the log shows the new network. If the issue occurs on only one network, keep the same server and settings for comparison. Changing servers while switching networks makes the results harder to interpret.

Always-on VPN and blocking connections that bypass the VPN are system settings separate from the app interface. If the bypass block is enabled, some traffic may be blocked when the VPN is disconnected. If you still cannot get online after stopping the client, the underlying network may not be broken; check the system VPN policy and adjust it to your needs rather than trying to work around the cause by restarting the phone.

Check per-app proxy settings and DNS together

With per-app proxying enabled, confirm whether the setting proxies only selected apps or bypasses selected apps; the two lists mean opposite things. If the browser is not in the intended list, its traffic may never pass through the client. After changing the list, reconnect the VPN, then fully close and reopen the test app so an old connection does not keep its previous route. A checked app icon alone does not prove that the app is using the proxy.

If only one app fails, check whether it relies on other components to make requests and whether it has separate proxy or secure DNS settings. The main app and its supporting components may use different network paths, so login can work while content fails to load. First establish a baseline with a browser confirmed to be within the proxy scope, then add other apps one at a time. For the Android setup steps, see the v2rayNG guide.

Enabling local DNS or traffic sniffing does not automatically fix every app issue. Sniffing can help routing identify a domain, but it does not decrypt app traffic or replace correct DNS and protocol settings. For domain-related errors, use the DNS section to identify where resolution occurs, then change one setting at a time. Check all server parameters against the complete configuration; do not fill in fields by copying a desktop screenshot.

For background disconnects, check battery and process limits first

If the connection drops when the screen locks but returns when you open the app, check battery optimization, background activity limits, data saver, and the manufacturer's auto-start controls. Use the system's app settings to allow the background activity needed by the client, and keep any required foreground service notification enabled. Settings names vary by device, so look them up in the actual system interface. There is no need to disable battery management for every app just to keep one client running.

If it still disconnects after background activity is allowed, note whether the drop happens after a network switch, a long idle period, or system memory cleanup. Compare with the screen kept on to distinguish network idle timeouts from process termination. A log that stops updating, a disappearing VPN icon, and a failed server reconnect are different clues; record them separately. Increasing the reconnect frequency can drain the battery without solving a system that keeps terminating the process.

If you need to reinstall, back up your subscription and custom rules first, then choose a package for your processor from the Android downloads page. Do not change the package and protocol at the same time. Final testing should cover foreground access, recovery after locking the screen, and switching between Wi-Fi and mobile data. If the problem persists, note the device OS, app name, steps that trigger it, and a redacted log, then return to the relevant troubleshooting section to narrow it down.