V2Ray Setup Guide for All Platforms

01 / PREPARE

General preparation: separate the client, core, and subscription

A client is not a node or a subscription service

Before installing anything, separate these three concepts. v2rayN, v2rayNG, and v2flyNG are graphical clients that store configurations, launch a core, configure the system proxy, and display runtime logs. V2Fly and Xray are core families that handle inbound and outbound connections, routing, DNS, and transport protocols. A subscription URL is a node list maintained by a service provider. After reading the URL, the client converts that list into selectable server configurations. Installing a client alone does not create a usable node; having a subscription URL without a compatible client cannot route system traffic through those configurations.

For desktop platforms, v2rayN is the default choice. It offers a desktop edition and a classic WPF edition on Windows, plus corresponding packages for macOS and Linux. Menu locations may vary slightly by interface version, but the core concepts are the same: subscription groups store URLs, the server list stores nodes, the system proxy handles browsers and other system-aware apps, and TUN uses a virtual network interface to capture more traffic. On Android, v2rayNG with the Xray core is the preferred option; choose v2flyNG when you specifically need the V2Fly core family. Select the appropriate package by platform on the client page.

Record four basics before installation

Before configuring a client, confirm that the subscription URL is complete, the device clock syncs automatically, the current network can reach commonly used websites, and the system architecture is known. Subscription URLs usually begin with HTTP or HTTPS. When copying one, do not include spaces, line breaks, or punctuation added by a chat app. An incorrect system clock can disrupt TLS handshakes and certificate checks, often making a node appear available while connections fail immediately. Enable automatic time and time-zone settings before troubleshooting the client; this is more effective than repeatedly switching nodes.

The system architecture determines which package to install. Most Windows devices use x64. On macOS, choose between Apple Silicon and Intel packages. Mainstream Android devices generally use arm64; use a universal package when the architecture is unknown. On Linux, check both the architecture and the distribution’s package system: Debian, Ubuntu, and derivatives usually use deb, while Fedora, RHEL, and related distributions generally use rpm. Choosing the wrong format usually will not damage the system, but the installer may refuse to run or report an architecture mismatch.

Build a minimal configuration you can roll back

Do not change routing, DNS, transport parameters, and TUN all at once on the first run. The minimal setup has four steps: import the subscription, update it, choose a node, and enable the system proxy or mobile connection. Then use a browser to visit a website that is normally reliable and watch the client logs. Add routing and DNS only after the connection works; change one category at a time so you can identify what caused a problem. Many cases where “everything suddenly stopped working” are not simultaneous node failures, but the result of changing several advanced options without a traceable baseline.

Give the initial subscription group an easy-to-recognize name and keep the default routing settings. Do not manually edit node fields generated by a subscription before updating, because the next update will usually overwrite those changes. If one node needs custom transport parameters, duplicate it as an independent configuration, or check whether the provider supports server-side edits. Treat the subscription URL as sensitive configuration; do not include it in public screenshots, logs, or support posts. For troubleshooting, retain the error type, timestamp, and client state, while masking domains, user identifiers, and node addresses as needed.

Prepare one final rollback path: know where the system proxy switch is and how to restore normal networking after closing the client. On desktop, clear the system proxy before exiting when it is enabled; with TUN, disable TUN first and then quit. On Android, disconnecting releases the system connection. Once these basics are ready, installation differs mainly in interface and permissions; the underlying logic of subscriptions, nodes, routing, and DNS is the same across platforms.

02 / WINDOWS

Windows: v2rayN installation, subscriptions, and system proxy

Choosing between the desktop and classic WPF editions

v2rayN is the recommended Windows client. The download page offers desktop and classic WPF editions. The desktop edition uses a newer cross-platform interface and suits fresh installations or people who work across multiple desktop systems. The classic WPF edition follows the native Windows interface style, with denser menus, and is better for users familiar with the older workflow. Both support subscription management, node selection, system proxy, routing, and TUN, so there is no need to install both. If unsure, start with the desktop edition; choose WPF only for a clear compatibility, migration, or workflow requirement.

After downloading the complete installer, follow its prompts to finish installation. If User Account Control appears, verify the program name and confirm that it matches the action you just started before allowing it to continue. Prefer an installation path writable by the current user, and avoid placing program data in a directory subject to automatic cleanup. On first launch, v2rayN normally creates its configuration directory and prepares the core components. If the firewall prompts you, allow only the network scope you actually need; a typical single-user setup does not require unrelated inbound access to “prevent connection failures.”

Import the subscription and choose an active node

Open subscription group management, add a group name, paste the complete subscription URL into the URL field, and save it. Then run an update. Once the update succeeds, server entries will appear in the main list; saving the URL without updating leaves the list empty, which is expected. Select a node and set it as the active server; the status bar or list marker will show the current choice. A node name is only a label from the subscription, not a measure of connection quality. For the first test, choose one complete-looking entry instead of running a batch of speed tests.

When an update fails, first check for spaces at either end of the URL, confirm that a browser can open it, and verify that the group is enabled. Subscription content may be Base64 text, a collection of share links, or a structured configuration; the client determines the format from the response. Do not paste an entire subscription into a single-node editor, and do not put an individual VMess or VLESS share link into the subscription URL field. Import individual share links into the server list; subscription URLs belong in subscription groups. These entry points serve different purposes.

Enable the system proxy first, then decide whether TUN is needed

After selecting a node, start the service and set the proxy mode to automatic system-proxy configuration or another mode clearly labeled as enabled. Browsers and desktop apps that follow the Windows system proxy will then send traffic to v2rayN. The client manages its local listening ports, so manual entry is usually unnecessary. If an application has its own proxy settings, choose “Use system proxy.” Only when it ignores system settings should you check v2rayN’s current local HTTP or SOCKS port and configure it separately.

The system proxy is the best starting point because the path is short, permissions are limited, and disabling it is easy. Games, some command-line tools, store apps, and software with its own network stack may bypass it; use TUN only when necessary. TUN often requires administrator privileges and creates a virtual network adapter. After enabling it for the first time, retest DNS, LAN access, and sleep/wake behavior—not just whether a browser opens a page. If enabling TUN cuts off all networking, disable it first, verify that the system proxy still works, and then inspect the driver, routes, and DNS instead of adding more switches.

Common Windows proxy remnants and permission issues

The most common cause of losing connectivity after quitting is a system proxy still pointing to a closed local port. Reopen v2rayN, clear the system proxy, and exit normally. You can also open Windows Network & Internet settings and check for leftover manual proxy settings or setup scripts. Do not reset the entire network stack as a first step; that can affect other network software and saved settings. First verify whether the proxy points to a loopback address and whether the corresponding port is still listening. This usually identifies the problem.

If the client cannot write its configuration, settings disappear after an update, or logs report access denied, inspect the installation directory and controlled-folder rules in security software. Do not run the client permanently as administrator for everyday use; grant elevated privileges only when prompted for a feature that needs them. If TUN alone fails while the system proxy works, the subscription, node, and core are probably usable, so narrow the investigation to the virtual adapter, route conflicts, and permissions. If the system proxy also fails, return to the node, clock, subscription fields, and core logs.

Command-line programs may still be inheriting stale proxy environment variables. The PowerShell command below only reads the current environment; it does not change anything. If it outputs an obsolete address, remove it from the relevant terminal configuration or system environment variables instead of repeatedly switching client nodes.

Get-ChildItem Env:HTTP_PROXY
Get-ChildItem Env:HTTPS_PROXY
Get-ChildItem Env:ALL_PROXY

After Windows sleeps or changes networks, a virtual adapter or old route may not refresh immediately. Disconnect the client, wait for the network icon to recover, and start the service again. If this happens often, use the system proxy for everyday browsing and enable TUN only when more applications truly need to be captured. For the detailed first-run sequence, see the Getting Started guide; this section focuses on choosing an edition and diagnosing Windows-specific issues.

03 / MACOS

macOS: chip selection, permissions, and proxy setup

Confirm Apple Silicon or Intel first

When using v2rayN on macOS, start by checking the processor architecture rather than just the OS name. Open System Information or About This Mac. If it shows an Apple chip, choose the arm64 package for Apple Silicon; if it shows an Intel processor, choose the x64 package. The wrong architecture may prevent the app from opening or require an extra translation layer, adding variables and complicating diagnosis. The download page separates packages by chip, so confirm the architecture before installing.

Installation usually means opening the dmg and moving the app to Applications. If macOS displays a security prompt on first launch, use Privacy & Security in System Settings to see why it was blocked, then allow it only after confirming that the source matches the download you just made. Do not weaken the security policy for the entire system just to run one app. v2rayN may request separate permissions to change the system proxy or create a network extension; grant them when you actually enable those features.

Import subscriptions and choose a node

Open subscription settings, create a group, paste and save the subscription URL, then run an update. The macOS layout may differ from Windows, but it still centers on subscription groups, the server list, the active node, and proxy mode. After updating, select a node and start the service. “Subscription updated” does not mean traffic is being routed: the update only synchronizes configuration, while the proxy switch determines whether the system uses the client.

When copying a URL from a chat app, watch especially for line breaks and text substitutions. Paste it into a plain-text editor first, confirm it is one line, and then add it to the client. Query parameters at the end of a subscription URL must not be truncated. For certificate or handshake errors during an update, check the system clock, current network, and URL first. If only one node fails while others work, inspect that node’s fields instead of deleting the entire group.

The boundary between system and application proxies

With the system proxy enabled, Safari, browsers that follow system network settings, and many desktop apps will use the local proxy provided by v2rayN. Terminal commands and some development tools may not read the system proxy automatically; that depends on each tool. Do not conclude that the whole client is broken because a terminal request behaves differently. Verify with a browser that follows the system proxy as well. If a command-line tool explicitly supports HTTP or SOCKS, enter the local address and port shown by the client in that tool’s own settings.

Clear the system proxy before closing the client. If the app has quit but every webpage fails, open the network details in System Settings and check whether HTTP proxy, HTTPS proxy, or automatic proxy configuration remains enabled. The leftover address often points to a port on 127.0.0.1 where no process is listening. Disable that entry and networking should recover. There is no need to delete Wi-Fi settings, forget the network, or clear DNS first; remove the most direct proxy remnant.

TUN, network extensions, and LAN access

TUN on macOS involves a network extension or virtual-interface permission. After allowing it on the first prompt, you may need to enable the feature again before it takes effect. Confirm that the system-proxy mode works reliably first; if TUN fails, the most useful comparison is whether the same node works through the system proxy. If the system proxy works but TUN cuts off networking, check DNS capture, the default route, and conflicts with other network extensions. Multiple apps trying to capture all traffic can overwrite one another’s route priorities and DNS settings.

When you need printers, file shares, or router administration pages, keep LAN addresses on a direct route. Common private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16; loopback and link-local addresses should not be sent to a remote node either. Default routing rules usually include these exceptions, but verify them after customizing routes. If only LAN devices are unreachable, do not change the node protocol first; check whether a route is incorrectly sending private addresses to the proxy outbound.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

After switching between Wi-Fi, hotspots, and wired networks, an old system proxy may remain even though the local port returns after the client restarts. The correct order is to disconnect, switch networks, confirm basic connectivity, and reconnect. If a subscription can update but webpages cannot open after the switch, inspect the active node, proxy mode, and DNS. If the subscription cannot update either, first rule out the new network’s captive portal and basic reachability.

The key to macOS is not adding special settings, but respecting system permissions and network-extension boundaries. Keep the setup simple when the system proxy is enough; enable TUN only when more apps need to be captured; keep private addresses direct when LAN services are required. After each network-extension change, test a browser, terminal, and LAN device. This exposes boundary problems faster than testing only one webpage.

04 / LINUX

Linux: packages, desktop proxy, and TUN permissions

Choosing deb, rpm, and the right architecture

Use v2rayN on Linux desktops. Before downloading, confirm the distribution’s package system and CPU architecture. Debian, Ubuntu, Linux Mint, and similar systems generally use deb; Fedora, RHEL-based distributions, and systems managed with rpm use rpm. Use the x64 package on x86_64 devices and the arm64 package on arm64 devices. Run uname -m in a terminal to check: the common output x86_64 maps to x64, while aarch64 maps to arm64.

uname -m
cat /etc/os-release

For a local deb package, let apt resolve dependencies when possible; for an rpm package, use the distribution’s current package-management command. Replace the filename in the commands below with the actual file downloaded to the current directory; do not copy a name that does not exist. A graphical software center can also install the package, but terminal output is more useful when dependencies fail.

sudo apt install ./v2rayN-linux-x64.deb

sudo dnf install ./v2rayN-linux-x64.rpm

If the installer reports an architecture mismatch, choose the correct package instead of forcing the check. If desktop runtime libraries are missing, confirm that the distribution version is still supported and install dependencies from the system repositories. Do not mix library files from unrelated sources. Once the app starts, check that its window, tray icon, and configuration directory belong to the current user. Running a graphical client as root long-term can leave configuration files owned by root, preventing the normal user from saving settings later.

Import subscriptions and account for desktop-environment differences

The v2rayN subscription workflow is the same as on other desktop platforms: create a group, paste the URL, save, update, and choose an active node. The main difference is the Linux desktop environment. GNOME, KDE, and other desktops do not expose or propagate system proxy settings in exactly the same way. Browsers can usually read the desktop proxy, while terminal programs, containers, and background services often cannot. Start verification with a desktop browser; configure command-line tools separately only after the core and node work.

Some lightweight desktop environments lack a unified system-proxy interface, so v2rayN’s “Set system proxy” may not cover every app. Check the client’s current HTTP and SOCKS ports and enter them in the target app’s own proxy settings. For a temporary test in the current terminal, you can set environment variables; closing the terminal rolls them back and avoids writing a dead port permanently into your shell configuration.

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
export ALL_PROXY=socks5://127.0.0.1:10808

Example ports only illustrate the format; always use the values shown in the client. If v2rayN changes its local ports, update the environment variables too. Different tools may read variables with different capitalization. Run env | grep -i proxy to inspect the current session. If the command line works but the browser does not, the desktop proxy is probably unset. If the browser works but the command line does not, the tool probably did not inherit the desktop proxy. These cases should not be conflated.

Permissions and route checks for TUN

Enabling TUN on Linux requires access to /dev/net/tun, creation of a virtual interface, and route changes. v2rayN may use a privilege-escalation mechanism for these operations. If the interface reports that TUN failed to start, confirm that the kernel module and device node exist, then check the logs for permission errors. Do not run the entire app permanently as root. Instead, give only the component that needs network-management privileges limited authorization while keeping the user configuration owned by the regular account.

ls -l /dev/net/tun
ip address
ip route

Record the default route and DNS state before and after enabling TUN. If networking disappears completely, disable TUN and check whether the default route returns. If only domain names fail while a known address responds, focus on DNS. If LAN devices are unreachable, check whether private addresses were incorrectly sent through TUN. NetworkManager, systemd-resolved, and the desktop environment may all manage DNS; identify which layer is actually active instead of writing different servers in three places.

Sleep, tray behavior, and background processes

On some desktops, closing the window only hides the app in the tray; on others, no tray extension is available and closing the window exits the program. Confirm v2rayN’s quit behavior during first use so you do not assume it has closed while the system proxy remains enabled. Use the process list and listening ports to see whether the core is still running. If the system proxy points to a local port after the process has ended, browsers will fail to connect to every page.

After waking from sleep, the network interface name, default route, and DNS may be recreated. System-proxy mode usually only needs a reconnect; TUN mode may need to be disabled and enabled again. If logs still show an old interface after wake, let the system network settle before restarting the client. Containers and virtual machines have separate network namespaces, so the host’s system proxy does not automatically cover their traffic. To proxy a container, configure its proxy address explicitly and confirm that it can reach the host’s listening port.

The most important Linux troubleshooting distinction is between whether the client core is working, whether desktop apps read the proxy, and whether TUN has taken over system routing. Do not use one command’s output as a substitute for all three checks. A browser, a terminal request using proxy environment variables, and ip route correspond to these layers. Verifying them separately prevents desktop-environment differences from being mistaken for node failures.

05 / ANDROID

Android: v2rayNG, v2flyNG, and connection authorization

Choose the client and package

v2rayNG is the preferred Android client and uses the Xray core, making it suitable for most subscriptions and common protocol configurations. v2flyNG uses the V2Fly core and provides an alternative core family. Both clients offer arm64 and universal packages. Most mainstream phones released after 2015 can start with arm64; choose universal when the architecture is unknown, installation reports incompatibility, or broader device coverage is needed. Do not keep both clients connected at the same time; Android can hand network traffic to only one connection of this type.

When opening the package, Android may ask you to allow the current browser or file manager to install apps. Grant this permission only to the app performing the installation, and disable it in system settings afterward. If installation fails, check that the download is complete, the architecture matches, and no same-named app signed by a different source is already installed. Before uninstalling an old app after an overwrite fails, back up important client settings so subscriptions and manually added nodes are not lost together.

Import subscriptions, clipboard links, and QR codes

In v2rayNG, open subscription settings, add a subscription URL, save it, return to the main screen, and run an update. A successful update creates a node list; tap an entry to make it the active configuration. Use an option such as “Import from clipboard” for an individual share link. QR codes work well for individual nodes or configuration content the client can recognize. Subscription and single-node QR codes may look identical, so determine which one you scanned by checking whether the result appears in subscription management or the node list.

If scanning does nothing, check camera permission, that the QR code is fully visible, and for screen glare. There is no need to upload a sensitive QR code to an online recognition tool. Also watch for truncated text when copying links. If the node list is empty after an update, check that the group is enabled, the current core supports the subscription format, and the URL is not returning a login or error page. See the subscription import steps for details on the different entry points.

First connection and per-app proxying

Select a node and tap the connect button; Android will display a network connection authorization prompt. Allow it, and a connection indicator will appear in the status bar while the client log records the connection process. For the first test, keep the default routing and avoid complex per-app rules. Verify with a browser, then test other apps. Unlike desktop systems, Android does not require a separate “system proxy” switch; after authorization, the system sends traffic from matching apps to the client.

Per-app proxying controls which apps enter the client. The usual choices are to proxy only selected apps or bypass selected apps. Read the mode name carefully before configuring it so the logic is not reversed. System components, browser engines, and an app’s main process may use different packages. If an app still behaves unexpectedly, check whether it calls an external browser or system downloader. Do not enable per-app proxying during the first setup. After a global connection works, add or exclude apps one at a time.

Background limits, battery optimization, and network changes

A connection that stops after running for a while is often caused by Android’s background battery restrictions. In app info, allow v2rayNG or v2flyNG to run in the background and disable strict battery optimization for that client using the options provided by the device. Adjust only the current client; there is no need to make every app unrestricted. If a task cleaner force-stops background processes, exclude the client from its cleanup rules as well.

When switching between Wi-Fi and mobile data, the existing connection may fail briefly. Wait for the system to obtain an address and see whether the client recovers; if it does not, disconnect and reconnect manually. If Wi-Fi requires a captive-portal login, disconnect the client, complete authentication, and reconnect. If only one Wi-Fi network fails while mobile data works, the client configuration is probably fine. Check that network’s DNS, captive portal, or IPv6 path instead of reinstalling the app.

DNS, IPv6, and LAN access

If Android shows “connected” but domains do not open, check DNS first. The client’s built-in DNS, the system Private DNS setting, and remote node-side resolution can all affect the result. For an initial diagnosis, keep the client’s default DNS and confirm that Private DNS is not pointed at a server unreachable from the current network. If only a few domains resolve incorrectly, configure split DNS rather than changing every query path.

IPv6 availability depends on the current mobile network, Wi-Fi, and node configuration. If logs show a request selecting an IPv6 address and then timing out, try a DNS strategy that prefers the address family supported by the current link, or check whether the node supports that egress. Do not blame every timeout on IPv6; inspect the target address and failure stage in the log first. If LAN devices are unreachable, allow private addresses to bypass the proxy and confirm that per-app rules are not sending a file manager or casting component through an unsuitable outbound.

Menu names in v2rayNG and v2flyNG may change with interface updates, but the workflow remains stable: import a configuration, choose a node, authorize the system connection, and watch the logs. Complete this flow with default settings before handling per-app rules, DNS, and background limits; most Android problems then reduce to a single variable. When comparing the two clients, use the same node so you can tell whether the difference comes from core compatibility or the node itself.

06 / SUBSCRIPTION

Subscriptions and node management: updates, overrides, and compatibility

What a subscription update actually does

A subscription update is neither a speed test nor a core reinstall. The client requests the subscription URL, reads the response, parses node fields, and refreshes the server list in the corresponding group. Node names, addresses, ports, user identifiers, transport settings, and TLS parameters usually come from the subscription. After the update, the active node may remain selected or may need to be chosen again if its entry was removed. If an update succeeds but the connection does not change, first check whether the active node is still the old entry.

Subscription groups keep configurations from different sources separate. Instead of putting every subscription into one unclear group, name groups by purpose. Before updating a group, note the current active server. If the new list looks wrong, switch to another verified group and continue troubleshooting. Treat subscription URLs as sensitive because they may contain access identifiers; keep URL bars, QR codes, and complete node fields out of screenshots.

The boundary between automatic and manual updates

Manual updates are useful for first imports, immediate synchronization after a configuration change, and troubleshooting. Automatic updates suit long-term maintenance, but should not run too frequently. Repeated requests do not improve connectivity when the subscription has not changed. An automatic update failure may not affect already saved nodes; the client can often continue using its local list. Distinguish between an unreachable subscription URL and an existing node that cannot connect—they are different failures.

If a subscription returns empty content, webpage text, or a login page, the client may report a format error. Without exposing the URL, use a browser on the same device to check whether the response is what you expect. If the browser works but the client fails, inspect whether the system proxy is affecting the update path, whether the local network is replacing certificates, and whether the client supports the returned format. Use a proxy or direct access for updates according to the subscription’s reachability; no single mode works for every network.

Why manual edits get overwritten

Subscription nodes are generated from a remote list, so the next update usually rewrites their fields. Editing a node name, port, or transport parameter manually may be overwritten; that is normal subscription behavior. To preserve custom settings, duplicate the node as an independent server outside the auto-updated group, or edit it in the provider’s management interface and sync again. Directly editing generated output is fine for temporary tests, but not for long-term maintenance.

Routing and DNS are usually client-level settings and are not necessarily overwritten by node updates. Manage server fields and local policy separately: server fields define how to connect remotely, routing decides which outbound handles traffic, and DNS decides how domains resolve. If every website behaves differently after a node update, check the active node and server fields first. Only then inspect routing and DNS if the change affects specific domains.

Protocol fields and core compatibility

Subscriptions commonly include VMess, VLESS, and Trojan nodes. The protocol name is only the first layer; transport, TLS, security parameters, server name, path, and other fields also determine whether a connection works. A client recognizing the node name does not mean every field is complete. Log messages such as “unknown field,” “unsupported transport,” or configuration parse failures usually indicate that the subscription format does not match the current core’s capabilities.

On Android, compare core families with v2rayNG and v2flyNG while keeping the same node, network, and routing settings as consistent as possible. If a configuration works with one core but not the other, that does not prove the entire client is broken; a specific field may be implemented or supported differently. On desktop, confirm that v2rayN is using a core compatible with the node’s requirements. Inspect the actual configuration fields instead of guessing from the node name.

Layered checks for subscription problems

First check the URL: is it complete, still valid, and free of spaces? Second check the request: can the current network reach it, and is the response actually subscription content? Third check parsing: does the client recognize the format, and do logs report field errors? Fourth check connectivity: can the node resolve domains and complete TCP and TLS handshakes? Working through these layers is faster than repeatedly deleting and re-adding a subscription, and it preserves usable configuration.

If dozens of nodes in a subscription fail at once, suspect shared conditions first: device time, DNS, the network, a broad change to subscription fields, or the core configuration. If only one node fails, inspect its address, port, and transport parameters. If a node connects but specific websites fail, move to routing and DNS. This decision tree prevents every issue from being labeled a “dead subscription.”

The goal of subscription management is not a longer list, but traceable sources, update times, and an identifiable active node. Keep groups clear, retain one verified node for comparison, and record original values before changing advanced parameters. Even when subscription content changes, this makes it easier to tell whether the issue lies with the remote list, client parsing, or the local network.

07 / PROXY AND TUN

How system proxy, TUN, routing, and DNS fit together

The system proxy only captures apps that honor it

A system proxy essentially tells the OS and applications where to find a local HTTP or SOCKS entry point. Browsers and some desktop apps read the setting and pass requests to v2rayN. It does not forcibly intercept every packet, so games, command-line tools, background services, and apps with their own network stack may bypass it. Its advantages are low permission requirements, a clear path, and easy rollback, making it the best default for a first connection and everyday browsing.

The client usually listens on loopback addresses such as HTTP and SOCKS ports on 127.0.0.1. Loopback is accessible only from the same machine, which suits single-device use. If you enable LAN access, define the listening scope and firewall rules carefully; do not expose the port on every interface just to connect a local app. When configuring a proxy manually, the protocol and port must match. Putting a SOCKS port in an HTTP proxy field can look like a refused connection or a failed protocol handshake.

Why TUN captures more applications

TUN creates a virtual network interface and points system routes to it. The client then decides whether each connection should use the proxy or go direct. Applications do not need to understand a proxy protocol, so coverage is broader than with a system proxy. The trade-off is higher permissions and interaction with system routes, DNS, and other virtual networking software. TUN is not a “faster mode” and cannot repair a bad node; it solves the problem of applications that ignore the system proxy.

The order should be: confirm that the same node works through the system proxy, record the current DNS and LAN state, close other software that captures the default route, and then enable TUN. Test at least a normal domain, a LAN address, and a program that bypassed the system proxy. If the browser works but LAN access fails, check direct routing for private addresses. If all domains fail, inspect DNS. If only one program fails, check for a special protocol or an isolated network environment.

Routing rules are matched in order

Routing rules determine which outbound handles traffic. A common order is direct access for explicit private addresses first, proxy rules for domains or addresses that need it next, and a fallback action last. Order matters: once traffic matches an earlier rule, later rules usually are not considered. An overly broad domain rule at the top can prevent later direct rules from ever matching. When troubleshooting split routing, check the actual domain, the resolved IP, the matched rule, and the final outbound tag.

domainStrategy determines how routing uses domains and resolved addresses. AsIs matches the original domain first and suits configurations with clear domain rules; other strategies may resolve the address when needed before applying IP rules. Do not change routing strategy and DNS at the same time without understanding the behavior. Keep the default while testing, then adjust it for a specific need such as an unmatched domain rule or IP-based routing.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "proxy"
      }
    ]
  }
}

DNS leaks, remote resolution, and split DNS

DNS converts domain names into addresses, and DNS queries may take a different path from connection traffic. If a domain resolves locally while the connection uses a proxy, the result may be affected by the current network. If every query goes remote, local domains and LAN services may stop resolving correctly. Choose the resolution path by domain category and keep it consistent with routing. See DNS leak testing and configuration for practical steps.

When DNS causes problems, distinguish resolution failure from connection failure. Enter the DNS layer only when logs show an unknown domain or a DNS timeout. If an address was resolved but the TCP connection times out, inspect the node, route, or destination network. Browsers may also enable their own secure DNS and bypass system settings. For comparison testing, temporarily make the browser follow system DNS so the client, OS, and browser are not all changing resolution paths at once.

Leak prevention is not simply entering one server address; it means ensuring that app queries, system queries, and TUN capture have no unintended bypass. Compare system-proxy and TUN modes separately, because a system proxy usually does not forcibly capture all system DNS while TUN can handle queries more centrally. After changing settings, clear old caches or wait for them to expire so historical results are not mistaken for the effect of the new configuration.

Recommended progression

Stage one: use default routing and the system proxy to verify the subscription and node. Stage two: add direct access for private addresses and necessary domain rules, confirming each match. Stage three: configure DNS so its resolution path agrees with routing. Stage four: enable TUN and test more applications, LAN access, and sleep/wake recovery. Keep a rollback configuration after each stage. This may seem slower than enabling everything at once, but it saves substantial aimless trial and error.

System proxy, TUN, routing, and DNS are four connected layers with different responsibilities. The system proxy determines whether an app hands requests to the client. TUN determines whether system packets enter a virtual interface. Routing determines the outbound after traffic reaches the client. DNS determines how domains become addresses. Troubleshooting by responsibility is more durable than memorizing menu locations and remains useful across platforms and interface changes.

08 / DIAGNOSIS

Common configuration problems: troubleshoot by log stage

Identify the failing layer first

The full connection path can be divided into six layers: whether the local app reaches the client, whether the domain resolves, whether the client reaches the node address, whether the transport layer is established, whether TLS and other security layers complete, and whether the target request exits through the intended route. The error location in the log is more informative than “the webpage will not open.” Record the time, make one fresh request, and inspect logs around that timestamp so earlier errors and background retries do not obscure the result.

If the log shows no new connection at all, the app may be bypassing the system proxy, excluded by per-app rules, or outside the route captured by TUN. A DNS timeout points to the resolver and query path. A timeout connecting to the node address points to the current network, reachability, or port. A TLS handshake failure calls for checks of system time, server name, and security parameters. If the connection is established but the destination returns an error, continue with routing and the destination service instead of reinstalling the client immediately.

The subscription updates, but no node connects

This shows that the client can at least reach the subscription URL; it does not prove that the node path works. Confirm automatic time and time-zone synchronization, choose one node, clear old logs, and reconnect. If every node reports the same DNS error, inspect system and client DNS. If all time out while connecting to the node address, inspect the current network and routes. If all fail during configuration parsing, subscription format or core compatibility is more likely.

Do not cycle through dozens of nodes while watching only the interface color. After each switch, retain a complete log and compare the failure stage. The same stage suggests a shared condition; different stages may indicate node-specific issues. You can also compare system-proxy and TUN modes: if the system proxy works but TUN fails, focus on permissions, routes, and DNS capture. If both fail, look closer to the node, subscription, or core.

The client says connected, but webpages do not open

“Connected” usually means only that the client process or system connection has been established; it does not mean every request succeeds. First check whether the browser reads the system proxy or whether the target Android app is included in the per-app rules. Then look for a corresponding domain request in the log. No request means an interception-layer issue. A DNS query with no result means a DNS issue. An address that resolves but cannot connect points to routing or the node.

On desktop, also check that the system proxy address matches v2rayN’s current local port. An upgrade, configuration migration, or manual change may leave the OS pointing to an old port. A browser proxy extension may override system settings, so temporarily keep only one proxy path during diagnosis. If only one browser fails, test with another app that follows the system proxy to determine whether the problem is in the browser or the client.

Only some websites or apps fail

Partial failures usually involve split routing, DNS, IPv4 versus IPv6 selection, or an app-specific network stack. Check whether the failed destination matched the intended routing rule, then inspect the addresses returned by DNS. Confirm the matching form used by the domain rule: exact domains, subdomains, and keyword matches have different scopes. Rules that are too broad affect unrelated destinations; rules that are too narrow match only one hostname. Clear relevant caches after changing a rule and test again.

If an app fails while the browser works, check whether it supports the system proxy, uses UDP, or runs inside a container or virtual machine. The system proxy mainly covers HTTP-style requests; TUN captures more general traffic, but the client must also handle UDP as configured. On Android, check per-app package selection. In Linux containers, check the network namespace. A Windows background service may run under a different account context. These are interception-layer differences, not subscription-layer problems.

All networking breaks after enabling TUN

First disable TUN and confirm that basic networking and the system proxy recover. Second, check whether the virtual interface was created and whether the default route points where expected. Third, check whether DNS was changed to an unreachable address. Fourth, rule out route conflicts with other virtual-network software. Do not keep changing node protocols and subscription fields while the virtual interface itself is not working; those settings are unrelated to its creation.

If networking remains broken after disabling TUN, check for a leftover system proxy, the default route, and DNS. On Windows, inspect manual proxy settings; on macOS, inspect network proxy entries; on Linux, check environment variables, desktop proxy settings, and ip route. Restore basic connectivity before enabling TUN again. After frequent network changes or sleep, rebuild the client connection first rather than rebooting the device. Consider deeper system networking only if the route still will not recover.

How to read logs and what to share

Useful logs include timestamps, modules, error types, and context. Common keywords can be grouped into parse errors, connection timeouts, refused connections, handshake failures, configuration-field errors, and permission errors. When troubleshooting, copy several lines before and after the error and state the platform, client, whether you are using the system proxy or TUN, and whether the problem is reproducible. Do not share only one line containing “failed”; the same word can indicate entirely different causes at different stages.

Before sharing logs, mask subscription URLs, node addresses, user identifiers, authentication fields, and local personal paths. If a node name contains account information, mask that too. Protocol type, transport, error module, and event order are usually enough. For more common questions, visit the FAQ page. For the relationship between the ecosystem and its clients, see Project V, V2Fly, and Xray explained.

A repeatable recovery process

When settings have become difficult to track, stop adding parameters. Export or record the current configuration, then disable TUN, clear the system proxy, and restore default routing and DNS settings. Keep one subscription group, update it, choose one node, and run the minimum test through the system proxy. After it works, restore features in this order: routing, DNS, TUN, and per-app rules. Verify the logs and target behavior after each addition.

If the minimal configuration still fails, test from a known-good network to separate device configuration from the current network. Then compare another node from the same subscription to distinguish an individual node problem from a shared configuration issue. On Android, you can also compare core families with v2rayNG and v2flyNG, keeping the network and node unchanged. Change only one variable per comparison so the result remains meaningful.

The goal is not to eliminate every message in the log, but to confirm that requests enter the client as expected, resolve correctly, connect successfully, and use the intended outbound. Some retries and non-critical notices may not affect actual use. Fix the first error that interrupts the request before addressing follow-on errors. Once this order becomes familiar, troubleshooting remains effective even when interface labels change.