v2rayNG / v2rayN
V2Ray Troubleshooting
Find steps for your issue, from Android installation and VPN permissions to desktop proxy settings and connection problems.
Clients · Cores · Protocols
Basics
Which devices are v2rayNG, v2flyNG, and v2rayN designed for?
For Android, start with v2rayNG, which uses the Xray core. If you already have a V2Fly-oriented configuration, check field support before choosing v2flyNG. For Windows, macOS, and Linux, use the desktop client v2rayN. Choose based on your device’s operating system, then check the protocols, transport, and security settings required by the server. Even if both clients can import the same link, that does not mean both can connect to the server.
What’s the difference between a subscription URL and a single-node link?
A subscription URL periodically fetches a set of configurations. Add it to a subscription group, then update the subscription to load the nodes. A single-node link contains one configuration and can be imported directly from the clipboard or a QR code. If the server settings change, re-import the link or edit the configuration as directed by the provider. Both single-node links and subscription URLs may be shared as QR codes, so check the source instructions before choosing an import option.
Are Android VPN permission and desktop system proxy the same thing?
No. v2rayNG’s VPN mode uses Android VpnService to receive traffic routed by the system through a virtual interface. The first time it starts, you’ll usually need to approve the system prompt. Which traffic is routed also depends on per-app and routing settings. A desktop system proxy provides a local proxy address to apps that follow the system proxy settings; it does not automatically route traffic from every process. If a desktop app ignores those settings, check its own proxy options.
Can VLESS, VMess, Trojan, and REALITY be used interchangeably?
VLESS, VMess, and Trojan are different proxy protocols. REALITY is a security mechanism that can be used with specific protocols and cores; it is not a drop-in alternative at the same layer. The client and server settings must match. If the client reports unsupported fields after import, check the core, transport, and security settings, then ask the provider for a configuration compatible with your client. Simply changing the protocol name usually makes connection issues harder to diagnose.
Continue reading: Client comparison · Protocol and core terminology
APK downloads · Subscription import · System permissions
Setup
Which Android APK should I choose: arm64 or universal?
If your Android app environment supports arm64-v8a, choose the arm64 build, which is usually smaller. If you can’t confirm the supported ABI or your device uses a less common app architecture, start with the universal build, which includes multiple ABIs. Don’t rely on the processor model alone: some devices have 64-bit processors but run a 32-bit app environment. If the universal build won’t install either, check the Android version, available storage, and whether it conflicts with an installed app.
v2rayNG subscription import failed. What should I check first?
First check whether the URL wasn’t saved, or the group was created but contains no nodes. Open Subscription Group Settings, add a group, and enter the full subscription URL. Remove any leading or trailing spaces, but keep the query parameters. Save, return to the configuration list, and select Update Subscription from the menu. For a single-node link, use the clipboard import option. If the update completes but the list is empty, check the group filter and confirm that the provider returned a subscription format the client can read.
What if Android doesn’t show a VPN connection prompt the first time I connect?
Select a configuration first and make sure the client is starting in VPN mode. If you’ve already granted permission, Android may not show the prompt again; search for VPN in system settings to check the current connection. If another VPN is running, or another app has Always-on VPN enabled, check whether that connection can be disconnected before trying again. Organization-managed devices may restrict VPN permissions, so check with your device administrator.
Why does v2rayN report insufficient permissions when I enable TUN?
TUN mode creates a virtual network interface and adjusts routing, which may require system authorization. On Windows, close the client, then restart it as an administrator if prompted. On macOS and Linux, follow the system prompts to check authorization and required permissions. If it still fails, read the logs to distinguish a permission denial from an interface creation failure or a conflict with an existing virtual interface. Don’t treat disabling the firewall as a general fix, and don’t bypass permission restrictions on managed devices.
Get started: Android APK downloads · First connection guide
Per-app proxy · System proxy · Speed tests
Usage tips
How should I choose bypass mode for per-app proxying?
In v2rayNG, open Settings → Per-app proxy. With bypass mode on, selected apps are excluded from the VPN. With bypass mode off and per-app proxy enabled, selected apps are routed through the VPN. Reconnect after changing the setting, then test one selected app and one unselected app to confirm the scope. If an app opens an external browser or a separate component, also check whether the app that actually makes the connection is included.
How do I verify v2rayN’s system proxy is working?
Keep TUN off, select a node, then choose Set system proxy from the tray menu. Confirm that the proxy is enabled in system network settings. Then open a test page in a browser that follows the system proxy settings and check whether the client logs show the request. If the browser works but another app doesn’t, check whether that app has its own proxy toggle or an extension overriding the proxy settings. When finished, clear the system proxy through the client and confirm that a direct connection works again.
How should I group multiple subscriptions to make troubleshooting easier?
Create a separate group for each source and name it by purpose. Don’t use the subscription URL or its access parameters as the group name. When troubleshooting, switch to the affected group, update only that group, then check the update message, node count, and selected node. Keep manually imported configurations separate from subscription nodes so a subscription refresh isn’t mistaken for lost manual settings. Before changing a URL, note the original group name and filter so you can tell whether list changes came from the update or a display filter.
How can I avoid treating a single timeout as the final result when testing nodes?
Use the same test method on the same network. Test a known-working configuration first, then the one you’re troubleshooting. TCP latency mainly shows whether a connection to the server port can be established. Tests that send requests through the proxy also depend on the handshake, routing, and test target, so don’t compare the two types of results as if they were equivalent. If a test times out once, wait for the network to stabilize and test again, then cross-check with actual browsing. A speed-test result reflects only that test; it doesn’t indicate sustained throughput or prove that the connection will work reliably.
Setup guide: Subscription groups, routing, and DNS settings
Update failures · Timeouts · Disconnections
Troubleshooting
A subscription used to update, but now it fails. How do I troubleshoot it?
Start with the update message. For connection or DNS timeouts, check your network and the subscription domain’s DNS resolution. For 401 or 403 errors, check your account permissions, whether the URL has expired, and the provider’s access requirements. If the download succeeds but parsing fails, check that the response isn’t a login or error page. If the client offers an option to update through a proxy, first confirm that the proxy works. Keep existing groups if an update fails; don’t rush to delete the nodes. When reporting the error to the provider, never include the full subscription URL.
One node keeps timing out. How can I tell whether it’s a network or configuration issue?
On your current network, test another known-working node in the same group. Then test the problem node on a different trusted network. If only that node keeps failing, check the server address, port, and required transport and security settings, and ask the provider whether the service is running. If nodes generally fail on the same network, check basic connectivity and DNS first, then review the first client error in the logs. A connection timeout and a handshake failure point to different stages; don’t change multiple fields without a comparison to guide you.
The client says it’s connected, but web pages won’t load. What should I do?
Connected usually means the local service or VPN interface has started; it doesn’t confirm that traffic is reaching the remote server. Disconnect briefly to confirm your basic network works, then reconnect and visit two different domains in a browser. Check whether both requests appear in the logs. If neither does, check which traffic the proxy captures and review per-app settings. If the requests appear, investigate DNS resolution, routing, and remote handshake errors. Change one setting at a time, retest, then decide whether to restore the previous setting.
v2rayNG disconnects when the screen locks. Should I change battery settings first?
First reproduce the issue on a stable network. After unlocking, check the VPN status, whether the persistent notification is still visible, and the latest log entry. If the process exited or the system stopped the service, go to Settings → Apps → v2rayNG → Battery and check background restrictions; menu names vary by device. If the service is still running and disconnections happen only when switching between Wi-Fi and mobile data, check the network-switching and reconnection logs first. After changing one setting, repeat the screen-lock test for the same length of time.