V2Ray Troubleshooting

For Windows, macOS and Linux desktops, v2rayN handles subscription groups, system proxy settings and routing. On Android, v2rayNG with the Xray core is usually the first choice; consider v2flyNG if an existing configuration specifically depends on V2Fly. Similar names do not mean the apps or configurations are interchangeable, and desktop packages are not for phones. Choose a client for your operating system, then check that its core supports your node’s protocol and transport. Don’t assume an entire configuration will work just because the interface looks familiar.

V2Ray generally refers to the proxy tools and configuration ecosystem associated with Project V. V2Fly continues development of a core in that ecosystem, while Xray is a separate core fork. A GUI client stores subscriptions, lets you select nodes and generates runtime configuration; the core handles the actual connection. So, a client recognizing a share link doesn’t guarantee that its core supports every parameter in it. If REALITY or a particular flow setting won’t start, check both the client’s parsing results and the core logs—not just whether the node appears in the list.

A client manages configuration and connections; it is not a remote service itself. To connect, you also need a server address, port, credentials, protocol and transport settings, usually imported from a subscription URL or a single share link. A subscription URL retrieves a set of configurations; it does not belong in the server address field. Check that you trust the source and are authorized to use it, then update the subscription group and select a node. Subscriptions may contain access credentials, so never post a full URL, share link or QR code in a public forum.

On a Mac, open About This Mac from the Apple menu. If it shows an Apple chip, choose the arm64 build for Apple Silicon; if it shows an Intel processor, choose the x64 build. Android arm64 and universal packages are a separate choice—don’t confuse them with Mac downloads. Most mainstream Android phones released after 2015 can usually start with arm64, but the right choice depends on the app architectures supported by the device. For older devices, or if installation reports an architecture mismatch, try the universal build. It includes components for more architectures and is usually larger; it won’t make connections faster.

First identify what you have: a subscription URL, a single share link or raw JSON. Add subscription URLs in the subscription group settings, then update the group. Import individual share links through the appropriate option, such as importing from the clipboard. Handle raw JSON using a custom configuration method supported by the client. Remove leading or trailing spaces, line breaks and any explanatory text added by a messaging app. If the log says the format isn’t recognized, check that the URL returns configuration data—not a login or error page—and ask the provider for a client-compatible format. Don’t keep trying to import a regular webpage URL as a node.

Keep the working group and note the update error. Check whether the subscription has expired, its URL has changed or your current network can reach the subscription service. If updates require a proxy, select a working node first and check whether the client offers an option to update through the proxy. If the proxy itself is down, try a network that can reach the service. A URL opening in a browser doesn’t guarantee it returns the right format; check for login pages and access restrictions too. Don’t clear all your nodes up front—you could lose working connections and useful troubleshooting references.

First make sure the v2rayN core is running, then select “Set system proxy” from the system proxy menu. In System Settings, open the network proxy settings and check that the active Wi-Fi or Ethernet connection has the client’s local listening address and port. The exact menu names vary by macOS version. Close and reopen the app you’re testing. The system proxy only affects apps that honor that setting; an app’s own proxy options, environment variables or other proxy tools may override it. Don’t conclude that the system proxy is broken just because one command-line tool isn’t using it.

TUN creates a virtual network interface and changes network settings, so it usually needs additional authorization. Quit other VPNs and similar network-control tools, then follow the permission prompts for your client version. Windows may require administrator access; on macOS and Linux, the process depends on the client’s permission helper. Don’t reuse commands from another platform or repeatedly run the app with elevated privileges to mask an unknown error. First verify the node with the regular system proxy, then enable TUN separately. If it still fails, save the initial error and interface-creation logs, then check permissions and routing conflicts one at a time.

They work at different stages. “Set system proxy” determines whether apps that follow the system proxy send requests to the local client. “Bypass mainland China” is a routing preset that chooses direct or proxied outbound connections after traffic reaches the core. You can use both settings together, or apply global proxy rules to traffic entering the client. If an app never sends its requests to the client, changing the routing preset alone usually won’t help. Troubleshoot the traffic entry point first, then check rule matching and the final outbound route. The system proxy menu is not a routing mode switch.

Check how the test works before comparing results. A TCP connection test shows whether a port accepts a connection; an application-level latency test also depends on the handshake and the test server’s response. Neither directly measures download speed. For a useful comparison, keep the network, test target and time period consistent. First confirm that commonly used websites load, then check whether sustained transfers are stable. Don’t run simultaneous tests on many nodes and rank them by a single result—network congestion and server rate limits can skew the outcome. If a low-latency node still can’t reach a site, investigate DNS, routing and the remote exit instead of rerunning speed tests.

Record your current DNS settings first, then determine whether requests use system DNS, encrypted DNS in the browser or the core’s DNS. If only some domains fail, check logs for resolution errors, the path DNS requests take and possible routing loops. Don’t change every resolver and routing rule at once. With TUN, check which DNS traffic is intercepted and whether the resolver itself can be reached directly or through the proxy as expected. Test the same domain each time and clear relevant caches if needed. Changing DNS at random won’t fix an unreachable remote server or incorrect certificate settings.

Back up subscription group details, custom routes, DNS settings and any node parameters you maintain manually. Make sure credentials in the backup won’t be exposed. Before switching cores, confirm that the new core supports the protocol, transport, REALITY settings and flow control you use; matching protocol names alone don’t guarantee compatibility. Change one thing at a time: switch nodes and test the connection before changing the core or routes. Subscription updates may overwrite nodes generated from a subscription, so save a separate configuration before making long-term manual changes. If you use multiple devices, check client compatibility on each one instead of copying the entire runtime configuration.

Turn off the proxy first and confirm that your basic network can reach sites that are normally accessible directly. Then check the client logs. A connection timeout, connection refusal, DNS resolution failure and authentication failure are different issues—not all timeouts. Make sure the server address and port haven’t been changed by mistake, and check that your device’s clock is accurate. Then test the same node on another available network. If only one node fails, check that node’s service and settings first. If all nodes fail, look for a local firewall, network restrictions or a core that isn’t running. Avoid changing several settings at once, or it’ll be hard to tell what affected the result.

“Connected” may only mean the local service has started; it doesn’t guarantee that every request to a remote server will succeed. Check whether the client logs a request when you open a page in the browser. If there’s no log entry, check the system proxy, the browser’s own proxy settings and the local port. If there is an entry but the request fails, look for DNS, handshake or outbound routing errors. Check whether all sites fail or only specific domains. If both the system proxy and TUN are enabled, turn off one traffic-capture method and retest with the simplest setup. Don’t change DNS, nodes and routes all at once; trace whether the request reaches the client, then investigate each stage.

Check that the package matches your system architecture and OS requirements, and save the full error message. On Windows, distinguish a missing .NET Desktop Runtime from an application configuration problem; whether you need to install the runtime depends on the release package. On Linux, check the package type and missing dependencies. On a Mac, distinguish an unidentified developer warning from a file access issue or an actual crash. If you trust the source, follow the instructions in Privacy & Security in System Settings. Don’t treat every launch problem as a permissions issue or disable system protections across the board. If the problem started after an update, back up your settings and check the startup logs.

If internet access stops after quitting, check whether your system still points to a local proxy port that is no longer running. Reopen the client, choose “Clear system proxy” and then quit; also check whether another network tool is rewriting the settings. If you used TUN, make sure the virtual interface and routes have been restored. If only one app bypasses the proxy, check its network settings; command-line tools may also read proxy environment variables. Don’t expose the local listener on every network interface to fix an app on your own device. When asking for help, include your OS, client, traffic-capture method and a summary of the error. Redact subscription credentials and personal identifiers from logs first.