Field notesClient settings and connection troubleshooting

V2Ray FAQ

For a new install, first check the package type and import method. If it used to work but no longer connects, start with Troubleshooting. Note which step triggers the error, and change one setting at a time.

Basics

Know the difference between the client, core, and traffic entry point to find the right layer when an error occurs.

Are V2Ray, v2rayN, and v2rayNG the same software?

No. V2Ray usually refers to the proxy ecosystem derived from Project V, or specifically to one of its cores. v2rayN and v2rayNG are graphical clients for importing configurations, choosing nodes, and starting or stopping connections. Choose an installer based on your device; when troubleshooting protocol or transport compatibility, check which core is actually running. When reporting an issue, include the client and core versions separately: similar-looking interfaces do not mean both clients can read the same configurations.

Can the Xray and V2Fly cores be swapped directly?

Don't assume cores are interchangeable just because they share protocol names. Check the protocol, transport, and security layer used by the connection configuration, then confirm the target core and version support that combination. For example, if a configuration specifically requires Xray's REALITY feature, use an Xray version that supports it. To test another core, try one configuration in a separate group and keep the original group intact. If parsing fails, you won't need to import the entire subscription again.

What's the difference between a subscription URL and a single-node link?

A subscription URL retrieves a set of configurations. Usually, you save it in a subscription group and then update the group. A single-node link describes one connection and should be imported through the client's clipboard or QR code option. Before importing for the first time, confirm with the provider whether they supplied a subscription, a single-node link, or a configuration file. Don't keep switching import methods at random. Subscription links may contain access credentials, so when asking for help, share only the link type and error message—not the full URL.

What do the system proxy, routing rules, and TUN each do?

The system proxy tells apps that honor the setting where to send proxy traffic. When supported and authorized by the system, TUN uses a virtual network interface to receive traffic routed to it. Routing rules then decide which outbound connection handles traffic the client has received. When troubleshooting, first check whether the app's requests reach the client, then see where the rules send them. Changing routing rules usually won't help if the app isn't using the proxy at all.

For unfamiliar protocol or setting names, see the quick reference.

Setup

Choosing a package, importing a configuration, and granting permissions are separate steps. If authorization fails, you don't need to start over with package selection.

Which Android APK should I choose: arm64 or universal?

If you know your device supports arm64-v8a apps, choose arm64. If you're unsure which app architectures the system supports, start with the universal build. Don't rely on the processor model alone: a 64-bit chip may run a system that supports only 32-bit apps. Universal builds usually include multiple architectures, so they're larger, and they still require a supported minimum OS version. For an in-place update, distinguish an architecture mismatch from a signature conflict caused by installing from a different source.

What should I check first if my first subscription import fails?

First, make sure the import method matches what you received. Add subscription URLs to a subscription group, save it, then update that group. When copying the URL, check for leading or trailing spaces, line breaks, and missing query parameters. If the client says the response can't be parsed, ask the provider whether you need a subscription URL formatted for that client. If the import succeeds but the list is empty, switch to the new group and clear any search filters before checking for download or parsing errors.

How do I fix a TUN startup error that says I don't have permission?

First, confirm the error occurs when starting TUN on the desktop, rather than while connecting to a node. Check the current version's requirements for a virtual network adapter, system authorization, or background service. On managed devices, ask an administrator to verify permissions; don't disable security protections to bypass the prompt. If the logs indicate a virtual adapter or routing conflict, exit other clients that are capturing traffic normally, then try again. If you only need proxy access in a browser, test the configuration with the system proxy first.

Why does Android ask to set up a VPN connection the first time I connect?

Android clients typically use VpnService to receive device traffic. The first time you start a mode that needs it, Android asks whether to allow a VPN connection. Check the app name in the prompt and grant permission only if it matches the client you just opened. If startup still fails, check Android's VPN settings for another app using the connection or an always-on VPN. Resolve any conflicts and try again; you don't need to reimport your subscription because authorization failed.

Haven't installed it yet? See APK options and system requirements. Already installed? Follow the quick start guide to make your first connection.

Tips

Before changing app lists, rules, or background settings, choose one app and one test destination so you can compare results before and after.

In per-app proxy settings, what do selected apps and bypass mode mean?

First, check whether the list is an allowlist or a blocklist. Allowlist mode sends traffic only from selected apps through the VPN; bypass mode excludes selected apps from VPN traffic. Labels may vary by version, so follow the explanation shown beside the list. After changing the setting, reconnect and test one selected app and one unselected app. The list determines which apps enter the VPN; routing rules still determine whether requests from those apps go direct or through the proxy.

How can I tell which routing rule matched after changing the rules?

Test one destination and check the logs for the actual destination and outbound tag. With common first-match routing, put exceptions for specific domains before broader rules that could match them. Reconnect after making changes so you're not testing an existing connection. Also check whether the app passes the client a domain name or an already-resolved IP address; each may match a different type of rule. Change one setting at a time to identify which rule affects the result.

Android disconnects after the screen has been off for a while. Which setting should I change first?

Test the same node once with the screen on and once with it locked. If it disconnects only while locked, open the app's system settings and look for battery usage or background activity controls. If the system allows it, relax battery restrictions for the client—for example, set it to Unrestricted. If disconnections happen only when switching between Wi-Fi and mobile data, first check whether the connection is re-established after the network changes. There's no need to change both battery settings and node parameters at once.

How can I keep manually edited nodes when updating a subscription?

Back up manually edited configurations locally, or copy them to a group that isn't updated from a subscription. Subscription groups are usually maintained by a remote list, and an update may replace existing entries, so don't rely on edits there as a long-term backup. Note which configuration is active before updating, then check the selected entry and group afterward. Treat exported configurations containing connection credentials as sensitive files; don't upload them to public support tickets or cloud-sharing links.

Troubleshooting

Start by checking the scope: a problem affecting one node, one app, or one domain calls for a different troubleshooting approach.

A node test times out. How can I tell whether the problem is local or with the node?

On the same network, compare the configuration with another one known to work. Then test the original configuration on a different network. If several configurations time out, check whether the core has started, whether the local listening port is already in use, and whether the system clock is correct. If only one configuration keeps failing, verify the server address, port, and transport settings. Some test methods don't measure actual proxy requests, so rely primarily on real access attempts and logs from the same time period.

The client says it's connected. Why won't webpages load?

Connected usually means the client has started or is capturing traffic; it doesn't mean requests to remote servers are succeeding. Use an app that you know is routed through the proxy to visit a destination, then check whether the corresponding request appears in the logs at that time. If there is no request, check the system proxy, the app's own proxy settings, or the per-app list. If there is a request, check its outbound tag and error type. If every app is affected, disable the proxy and test the basic network first, then return to the client settings.

v2rayN has the system proxy enabled. Why is my browser still connecting directly?

First, determine whether the browser is ignoring the system proxy or whether its requests reach the client and are routed direct. Make sure v2rayN is set to “Set system proxy automatically,” then check that the system proxy address and port match the values the client is actually listening on. Check whether the browser's own proxy settings or an extension override the system settings. If the logs show the request with a direct outbound tag, check the routing rules instead of repeatedly toggling the system proxy.

A subscription that used to work suddenly won't update. How do I troubleshoot it?

Keep the existing list and update only the group that's failing. Save the update logs. For HTTP 401 or 403 errors, ask the provider to check your subscription access, expiration, and whether the URL has changed. For connection timeouts, first confirm that your current network can reach the subscription service, then check whether the client is set to fetch subscriptions directly or through the proxy. If the request succeeds but parsing fails, make sure the response contains subscription data rather than a login page before changing the URL or format.

Only some domains won't load. How can I tell if it's a DNS issue?

In the same app, test one failing domain and one working domain, then compare the logs. For resolution timeouts or domains that can't be found, check which DNS resolver the app is actually using. Note that the browser's Secure DNS settings may differ from the client's DNS settings. If the domain resolves but the connection times out or the TLS handshake fails, investigate the outbound route and transport. Don't draw conclusions by visiting a bare IP address; a site may rely on its domain name to select a certificate or service.