v2rayN Troubleshooting

v2rayN is a desktop GUI client for managing subscription groups, selecting servers, and configuring the system proxy and routing. The proxy core it launches handles the actual connections. v2rayNG and v2flyNG are Android clients built primarily around the Xray and V2Fly cores, respectively. Project V is a good starting point for understanding this ecosystem. Similar client names do not mean their configuration files are interchangeable. When troubleshooting, note the client version, the core actually in use, and the protocol. An open client window does not confirm that the core started successfully or that app traffic is passing through the proxy.

Windows users can choose between the v2rayN desktop edition and the classic WPF edition. macOS and Linux use the cross-platform desktop edition. The desktop edition uses Avalonia, while WPF uses Windows UI technology, so tray behavior, menu placement, and some system integrations may differ. Choose a package for your operating system and processor architecture, then pick the interface that best fits your existing configuration and workflow. Back up your settings before switching, and do not extract both editions into the same folder and overwrite files. If an issue occurs in only one edition, note the specific interface version and steps to reproduce it rather than assuming the subscription or server has failed.

Check your device's processor architecture or the device information provided by the operating system. On a 64-bit ARM device with a compatible runtime environment, the arm64 package is usually the right choice. If you cannot confirm the architecture, try the universal package, which includes components for multiple architectures but is typically larger. Do not rely on the device's purchase year: a 64-bit-capable processor does not guarantee that the operating system provides the corresponding app runtime. If installation reports incompatibility, check the system requirements. For a signature conflict, back up your settings and check the source and signature of the installed app; not every installation failure is caused by the architecture choice.

A subscription URL retrieves a set of server configurations and may be used to update them later. A single server link usually describes one connection, while a full configuration file may also include inbound and outbound settings, routing, and DNS. Each uses a different import option. Importing a subscription URL as a server link may result in an unrecognized entry or an empty list. A subscription URL is not necessarily a webpage you can browse to; what appears in a browser does not prove the content is in a format the client can use. These URLs often contain access credentials, so hide the full URL and any identifying information before sharing screenshots or logs.

First, check whether you entered a subscription URL or a single server link. Add subscription URLs to the address field in a subscription group, then update that group. Import a single link using the corresponding link-import option. Check for spaces, line breaks, text added by a messaging app, or missing parameters. If the update request succeeds but the list is still empty, check the client logs for parsing errors and confirm the provider did not return a login page, expiration notice, or error page. Avoid deleting all your servers to troubleshoot. Keep the existing group and create a separate test group to check the source and response content.

Auto-configuring the system proxy changes the proxy settings that apps can read; it does not guarantee every program will use them. First confirm the proxy core is running and the local port is listening. Then check that the system proxy address and port match the client settings. Browser extensions, separate proxy settings, enterprise policies, or another proxy app may override the system settings. After making changes, restart the browser and test again. Compare an app known to use the system proxy with the one having trouble to distinguish an entry-point issue from app-specific behavior. If an app does not use the system proxy and needs to be routed, consider TUN rather than switching to global routing as a first step.

TUN creates a virtual network interface and changes routes, so it usually requires administrator authorization or the platform's equivalent elevation process. Close any duplicate client instances, relaunch with the required authorization for your platform, and check the first error in the logs. Permission errors, interface creation failures, and route update failures occur at different stages; repeatedly toggling the setting will not fix them. If the device is managed by an organization, follow its device policies instead of trying to bypass them. Check whether another virtual adapter or VPN is using the routes. During troubleshooting, turn off TUN and confirm the system proxy works, then restore virtual adapter routing and DNS settings one at a time.

After importing, confirm the target group contains recognized server entries. Select one as the active server and check that the core starts successfully. Then choose the system proxy mode you need, visit a test page in an app that uses that proxy entry point, and check the relevant access records or routing logs. An entry in the server list only confirms that the configuration was saved; a successful test does not mean every app can connect. Change one condition at a time during testing—for example, keep the server unchanged and switch only the system proxy setting. This lets you verify configuration parsing, server connectivity, the traffic entry point, and route matching separately, without losing track of what caused a change.

The system proxy determines whether an app sends traffic to the local proxy entry point. Routing rules determine which outbound the core uses for traffic that reaches it. Auto-configuring the system proxy does not send every destination through the proxy, and global routing does not capture apps that ignore the system proxy. When using presets such as bypassing mainland China, understand how domains, IP addresses, and rule databases are matched. If a website does not behave as expected, first check whether its traffic reaches the core, then inspect the matching rule and outbound tag. You can temporarily adjust a preset to troubleshoot, but note the original setting and restore it afterward. For lasting exceptions, a narrowly scoped rule is easier to maintain than a broad one.

In the subscription group settings, make sure updates are enabled and enter the auto-update interval as specified by the field. The unit is minutes. Set the frequency according to the subscription provider's requirements; updating too often may trigger request limits and make troubleshooting noisier. Updating through a proxy is useful when the subscription service is unreachable directly but a working proxy is available. The active server and proxy core must already be working. If all servers are down and the subscription depends on them to update, you have an update dependency. Restore direct access or use an existing working configuration first. After changing the settings, run a manual update and check the logs, then confirm that automatic updates run as expected.

First check the logs to see whether the failure is DNS resolution, a connection error, or a request sent through the wrong outbound. An app's secure DNS, system DNS, and core DNS may use different paths, so changing one may not affect the others. With TUN enabled, check whether DNS requests are captured and whether they are looping back into the same entry point. DNS results can also affect routing rules that match IP addresses. Change one DNS setting at a time and retest after reconnecting the app; do not change all resolvers and routing rules together. Accessing a service directly by IP may also break certificate hostname matching, so it is not a permanent fix.

Start with the backup or export feature provided by the current client. Keep subscription groups, manually added servers, custom routing rules, and any required settings, and note the original client and core versions. Exported files may contain subscription credentials and server authentication details, so store them securely and do not upload them to a public cloud drive or share link. When moving to a different platform or client, do not assume you can overwrite the entire data directory; first check that the import format and fields are compatible. After restoring, verify local ports, system proxy settings, TUN, and custom paths one by one. In particular, do not reuse absolute paths from the old system. Keep the original backup until the new setup is verified to make rollback easier.

A timeout only means the current test did not finish within the allotted time; it does not prove the server is permanently down. Check the client's test method and test address, then verify your local network, system clock, server domain resolution, and protocol parameters. Handshake failures, unreachable destinations, and unavailable test sites can look similar, so use the core logs to tell them apart. Keep the network unchanged and compare with a known working configuration, or keep the configuration unchanged and test on another network. If several configurations fail at once, check the local entry point, network, and core startup before deleting servers one by one or repeatedly reinstalling the client.

The client's running status, a successful test request, and an app's actual connectivity are three separate things. First check whether the affected app uses the system proxy or is captured by TUN, then verify the active server and routing outbound. If only domain access fails, focus on DNS. If only some sites have issues, check rule matches, connection logs, and the status of the destination service. Also rule out interference from proxy extensions, old manual proxy settings, and security software. Test in a regular browser window and another app, and reconnect to avoid reusing connections on the old path. Do not assume the whole connection path is working based only on a status icon, or treat global routing as a universal fix.

Check the update logs first to distinguish an expired URL, DNS resolution failure, connection timeout, certificate error, or server rejection. For certificate errors, check the device date, time zone, and system trust store, then verify the subscription domain. Do not treat disabling certificate validation as a routine fix. If requests are being rate-limited, stop retrying manually and increase the update interval as required by the provider. For an expired URL or authentication error, check the subscription validity period and access credentials; reinstalling the client usually will not help. When sharing logs, include the error type and where it occurred, but hide the full subscription URL and any authentication parameters before sending them to support.

Check whether the system still points to a local proxy port that is no longer listening. If needed, restore the previous network proxy settings through the system settings. With TUN enabled, use the client's normal shutdown process to stop virtual adapter routing before exiting, so the network state can be restored cleanly. Multiple proxies or VPNs may each change the system proxy, default route, or DNS; leave only one active during troubleshooting. If a port is occupied, identify the program using it before taking action—do not terminate system processes at random. Once basic connectivity is restored, enable features one at a time to find what reproduces the issue. Before changing routes on a remotely accessed device, prepare a way to roll back.