v2rayN / v2rayNG
Setup and Connection Troubleshooting

Choose a client based on your device. Use v2rayN on Windows, macOS, and Linux. On Windows, choose between the desktop and classic WPF editions. For Android, start with v2rayNG, which uses the Xray core; consider v2flyNG if you need the V2Fly core. The client interface and its core are separate layers, so a protocol name alone cannot tell you whether it is supported. Before importing a configuration, check your provider’s requirements against the client and core’s current support. All three clients need a working configuration; installing one does not by itself enable a connection.

Think of a client as a tool for reading configurations and managing connections. A subscription URL usually retrieves a set of configurations; save it in a subscription group, then update the group. A node share link usually contains one connection configuration; import it from the clipboard or scan its QR code. Don’t use your provider’s account page URL as a subscription URL, or paste multiple share links into the subscription URL field. Subscription URLs may contain account identifiers. When troubleshooting, describe the format and error without showing the full URL in public screenshots.

First, distinguish how traffic enters from how outbound connections are routed. A system proxy writes proxy settings to the operating system; only apps that follow those settings will use it. TUN receives eligible traffic through a virtual network interface, but what it captures also depends on routing, exclusions, and the system environment. Routing rules determine whether connections entering the core go direct, through a proxy, or to another specified outbound. Enabling TUN does not mean every connection will use the proxy, and choosing bypass-mainland routing does not mean every app will be captured by the core. When setting things up, verify one traffic entry method first, then check the routing results.

Don’t judge by the import result alone. A successful subscription parse means the client recognized the content; it doesn’t mean the current core supports every parameter in every entry. VMess, VLESS, and Trojan are protocol names; REALITY is a connection security configuration. Transport and security settings must also be supported and matched correctly. If some entries fail to start, check the logs for unsupported fields or invalid parameters, then confirm which core is selected and whether the client is up to date. Keep the provider’s configuration unchanged; don’t guess ports, transport paths, or server names from the protocol alone.

Check your device’s processor architecture or system information first. Most recent Android phones can use the arm64 package, but a 64-bit-capable processor doesn’t guarantee that the installed system provides a compatible runtime. Don’t decide based on the phone’s release year alone. If you’re unsure of the architecture, choose the universal package, which is usually larger. If installation reports an incompatible device, check the system requirements and package architecture. If it reports a conflict with an existing app, confirm it’s the same client and that the signing keys match. Uninstalling can remove local settings, so use the client’s backup option to save anything you need first.

Open the subscription group settings and confirm the URL is saved and the group is enabled. Return to the main window, choose Update all subscriptions (without proxy) from the subscription group menu, then select the group to view the results. Adding a URL only saves the source; it doesn’t fetch the configuration automatically. If the log says the request succeeded but no entries appear, check whether the URL returned subscription data or a login page, and whether the current client can recognize the format. Don’t keep adding the same URL. Keep one group and troubleshoot fetch errors separately from parse errors.

Make sure the clipboard contains a complete node share link, not explanatory text, a webpage title, or a fragment with extra punctuation. When copying, include the protocol prefix and don’t edit encoded content. If you have a subscription URL, add it in the subscription group settings and save it, then update the subscription instead of repeatedly using the node import option. If a QR code won’t scan, check that the image is clear and complete. If importing still fails, check the formats supported by the client and follow the provider’s import instructions. Don’t upload subscription content to an unfamiliar conversion site.

Turn off TUN and check the logs to see whether the failure occurs at the permission, virtual interface, or routing stage. On Windows, close the client and restart it as an administrator if required by your version, then enable TUN again. Authorization and helper service requirements differ on macOS and Linux; follow the instructions for your platform rather than applying Windows steps. If the system blocks the initial authorization, check the app’s source and the exact prompt. If permissions are in place but TUN still fails, check whether another VPN or virtual network tool is also managing traffic. Quit them one at a time and retry; don’t delete system network interfaces.

Choose based on whether the subscription URL is currently reachable directly; neither method is right for every situation. If you’re setting things up for the first time and don’t have a working connection yet, try updating without a proxy. If the URL is only reachable through an existing proxy, first confirm that connection works, then update through the proxy. When an update fails, note the status code and error type to distinguish an invalid URL, an expired login, a parse error, or a network timeout. Updating a subscription only fetches its contents again; it doesn’t renew an account or manage your provider’s quota or expiration date.

Choose a routing mode based on what you need to access. Bypass Mainland generally uses domain and IP rules to send matching destinations in mainland China direct, while handling other connections according to the rules. Global Proxy generally routes connections entering the core through the proxy first, but the active rules still determine the result. After switching, retry the destination and, if needed, close the app’s existing connections so they don’t keep using the previous route. If results don’t match expectations, check rule order, rule sets, and DNS resolution before replacing a node. Apps not captured by the system proxy won’t start using the proxy just because you changed routing modes.

Sharing a subscription mainly lets each device fetch node configurations from the same source; it doesn’t automatically sync all local client settings. Check system proxy, routing, DNS, TUN, or VPN mode separately on each device running v2rayN or v2rayNG. Settings with the same name may also work differently. A node QR code or share link transfers a single entry, not a full backup. Before migrating, confirm the target client supports the backup format and keep the configuration on the old device. Also check your provider’s device and simultaneous connection limits; a successful update doesn’t mean you can connect as many devices at once as you like.

Use the client’s backup or export option to save subscription groups and any local settings you need. Note any custom routing, DNS, and proxy entry settings too. Backups may contain subscription URLs and connection credentials, so store them somewhere secure. Before restoring across clients, interface versions, or platforms, confirm the target version supports the format. Don’t overwrite an unfamiliar configuration directory. After updating, check that your groups are still there, test a saved entry, then restore custom settings. If the new version causes problems, keep the error details and original backup; repeated uninstalling can erase useful troubleshooting clues.

First confirm your local network works and your system clock is accurate. If only one entry times out, compare it with other entries in the same subscription. If they all time out, check your local network, firewall, core startup, and subscription expiration first. TCP tests, actual connection tests, and browser checks measure different things; one timeout doesn’t prove that every app is unable to connect. Check the logs for DNS resolution failures, connection refusals, or handshake failures, then address the relevant stage. Don’t delete nodes in bulk or change every protocol parameter based on a single timeout.

Treat “connected” as confirmation that the local service or VPN has started, not proof that the remote destination is reachable. Check that the right entry is selected and the core started successfully. Then try one destination expected to go direct and one expected to use the proxy. If both fail, check traffic capture, DNS, and conflicts with other VPNs. If only the proxied destination fails, focus on the node and outbound logs. If only one site fails, check which routing rule matched and how its domain resolves. Change one setting at a time and retry; don’t switch DNS, routing, and TUN all at once, so you can tell what made a difference.

In v2rayN’s system proxy menu, confirm that Set system proxy automatically is selected. Then check that the proxy address written to the operating system matches the current local listening port. Some apps have their own proxy settings or don’t use the system proxy at all. In that case, enter the actual listening protocol and port in the app, or use TUN once you understand what traffic it captures. If your browser has a proxy extension, check whether it overrides the system settings. If the internet still doesn’t work after closing the client, check for leftover system proxy settings, restore them to suit your current network, and test the basic connection again.

Start by identifying where the update failed. A request timeout means no response arrived within the allowed time; check whether the URL is reachable and which network route the update uses. For responses such as 401 or 403, check the URL, account status, and provider restrictions; repeated retries won’t fix authentication problems. If the request succeeds but parsing fails, check whether the response is a login page, an error page, or an unsupported subscription format. Keep the full query string when copying the URL, and watch for trailing spaces. Before sharing logs or screenshots, redact subscription URLs, credentials, and personal information. Then give the provider the error type.