v2rayN for Every PlatformComplete Setup Guide

1. How to Read This Guide and Understand the Full Setup

What the client, kernel, and subscription each do

A working setup has three separate layers: the client interface, the proxy kernel, and the subscription data. v2rayN, v2rayNG, and v2flyNG are graphical clients that display nodes, save preferences, and use system capabilities. Xray or V2Fly is the kernel that handles protocols, routing, and connections. A subscription is a configuration set supplied by a service provider, typically containing the server address, port, user ID, transport method, TLS parameters, and name. After importing a subscription, the client does not immediately route every application through the network. It passes nodes to the kernel first, then the system proxy or TUN determines which application traffic enters the local proxy endpoint.

A client showing “started” and a browser actually using the proxy are two different things. A healthy kernel only means that a local listening port has been created. Whether the browser uses that port also depends on system proxy settings, the browser’s own proxy policy, routing rules, and DNS handling. Troubleshoot the data path one stage at a time: can the subscription be parsed, can the selected node connect, is the local endpoint listening, does the application send requests to it, does routing choose the correct outbound, and does DNS return a usable result? Reinstalling repeatedly while mixing these layers together rarely reveals the real cause.

Recommended clients by platform

For desktop platforms, use v2rayN as the default choice to manage subscriptions, routing, and logs through a consistent interface. On Android, v2rayNG is the first choice; use v2flyNG when you specifically need the V2Fly kernel path. Their basic workflows are similar, but do not assume that their configuration databases or kernel capabilities are fully interchangeable. When switching clients, re-import the original subscription instead of copying the other client’s internal data directory.

The standard order for a complete setup

1. Confirm the platform and architecture. Identify the operating system, processor architecture, and distribution package format, then choose the matching installation file in the Download Center.
2. Install the client. On first launch, handle system permissions, firewall prompts, or network-interface authorization and confirm that the interface opens normally.
3. Import and update the subscription. Create a subscription group, enter the complete URL, run one manual update, and check that the node list appears.
4. Choose a node and mode. Verify the connection with the basic system proxy first, then decide whether to enable TUN based on the applications that need coverage.
5. Verify the request path. Check client logs, browser access, and system proxy status. Do not treat a single latency result as proof of a working connection.
6. Adjust routing last. After the basic connection works, add direct, proxy, or block rules one category at a time.

A system proxy is suitable for browsers and desktop applications that follow system network settings. It is simple to configure and has a clear scope. TUN uses a virtual network interface to capture a broader range of traffic, making it useful for applications that ignore system proxies, send only UDP, or build their own network stack. It also introduces variables such as administrator permissions, routing tables, DNS capture, and conflicts with other network tools. The sensible approach is not to enable everything by default, but to start with the smallest configuration, confirm the main path, and expand coverage afterward. That is why every platform chapter follows the order “installation, subscription, system proxy, TUN, platform issues.”

2. Before You Install: Platform, Architecture, Subscription, and Permissions

Identify the operating system and processor architecture

Before downloading, confirm the operating system version, processor architecture, and package type. Common Windows desktops use x64. On macOS, distinguish Apple Silicon from Intel. On Linux, check not only x64 and arm64 but also whether the distribution uses deb or rpm packages. Most recent Android devices use arm64; consider a universal package only when the architecture is unknown or installation fails. The wrong architecture usually causes the installer not to launch, an incompatibility warning, or an app that exits immediately after installation. This has nothing to do with subscriptions, nodes, or network conditions and cannot be fixed by changing proxy parameters.

On Windows, open “Settings → System → About” to view the system type. On macOS, open “About This Mac”: choose Apple Silicon when the chip field shows an Apple processor, or Intel when it shows an Intel processor. On Linux, run uname -m in a terminal; x86_64 corresponds to x64, while aarch64 or arm64 corresponds to arm64. Android architecture usually does not require an extra tool: try the arm64 package first, then use the universal package only if the system explicitly rejects it. Do not upload device information to unknown hardware-detection sites.

uname -m

# Check package architecture on Debian, Ubuntu, and derivatives
dpkg --print-architecture

# Check machine architecture on Fedora, Rocky Linux, and similar distributions
rpm --eval '%{_arch}'

Prepare a valid subscription and basic information

A subscription URL is the client’s entry point for retrieving a configuration set and must remain complete. Common copying mistakes include dropping trailing parameters, introducing line breaks, copying displayed webpage text instead of the actual URL, or using a subscription that the provider has disabled. Record the subscription name, update URL, and purpose clearly, but never expose the full URL in screenshots, logs, or public support requests because it may contain a token that identifies your account. Create separate groups for different sources in the client so that multiple subscriptions do not overwrite one another and obscure where nodes came from.

If the provider offers multiple subscription formats, choose the one explicitly marked for V2Ray, Xray, or the relevant client. A normal webpage URL, a dashboard login URL, and a subscription URL are different things. A successful import means more than “no error appeared”: recognizable configuration entries should appear under the subscription group, and a manual update should show that retrieval and parsing completed in the log. If the list is empty, inspect the subscription response and format before changing TUN, DNS, or routing modes.

Permissions, time, and network conditions

A client’s basic proxy features usually need only user permissions. TUN may need to create a virtual network interface, write routing-table entries, or modify DNS, which triggers administrator authorization. Grant access through the system’s native prompt. On managed devices, organizational policies may restrict these permissions; check the device-management rules instead of repeatedly relaunching the client. Windows Firewall may ask about network access the first time the kernel runs. macOS may request permission for network configuration. Linux may use polkit or terminal-based privilege escalation. Android shows a system VPN authorization dialog on the first connection. After authorization is denied, the interface may still appear usable, but traffic capture will not be fully established.

Device time also affects TLS handshakes and time-limited authentication. Enable automatic time synchronization and verify the time zone. An incorrect date, time, or time zone can make a certificate appear not yet valid, expired, or outside the expected authentication window. Another preparation step is to reduce network variables temporarily: during the first setup, disable other proxies, network filters, and similar virtual adapters, keeping only the current client active. Verify first on a stable home or mobile network. If a public network requires a sign-in page, complete authentication before enabling the proxy; otherwise every connection may be redirected to the login page.

Build a recoverable configuration workflow

You do not need to migrate an entire configuration of unknown origin before installation. A safer approach is to save the subscription source, routing intent, and only a few necessary preferences, then rebuild the setup in the new client. When upgrading an older client, stop the running kernel first, then replace or install alongside it according to the current installation method. Do not run two instances listening on the same local port; the later process will report that the address is already in use. Avoid placing portable directories in locations that frequently require elevated write access. Logs, databases, and update files all need stable write permissions.

When preparation is complete, choose a client by platform in the Download Center. The download page provides the Windows desktop and classic WPF editions, macOS packages for both chip architectures, Linux deb and rpm packages, and installation entry points for v2rayNG and v2flyNG on Android. Choose an installation file based only on platform and architecture, not on the subscription protocol. VMess, VLESS, and Trojan are kernel configuration protocols imported after installation; they do not require separate clients.

3. Windows: v2rayN Installation, Subscriptions, and System Proxy

Choose the desktop or classic WPF edition

v2rayN is the recommended Windows client. The Download Center offers a desktop edition and a classic WPF edition. The desktop edition uses a newer cross-platform interface and suits users who want a similar experience across macOS and Linux. The WPF edition retains the classic Windows layout for users familiar with older menus and workflows. Both editions manage subscriptions, start the kernel, and configure the system proxy, but their layouts may differ. Do not run both editions at the same time; they may compete for local ports, system proxy state, or configuration directories.

When installing or extracting the client, use a stable directory with normal user write permissions. If you use an installer, follow the system wizard. If you use a portable package, extract it completely before launching it rather than running it from a compressed-file preview. If Windows Firewall prompts you on first launch, allow access on the current trusted network scope so local applications can reach the client’s listening port. The client usually does not need to provide a service to the local network, so do not enable “Allow connections from the local network” without a clear reason.

Import a subscription and choose the active node

Open subscription-group management, create a recognizable group name, paste the complete subscription URL, and save it. Saving records the source only; you must then run “Update current subscription” or “Update all subscriptions.” After the update, return to the server list and confirm that the name, address type, and transport details appear. The number of nodes does not prove usability. Set one configuration as the active server and perform a real connection test. If the list remains empty, inspect HTTP status, parsing errors, or format messages in the log instead of repeatedly creating the same group.

Latency tests are useful only for initial filtering. Some servers do not answer ordinary probes but can establish a real proxy connection; others may show normal latency while the actual handshake fails. A more reliable method is to run a real-connection latency test for the selected node, enable the system proxy, and open a previously uncached webpage. Watch the log for successful connections, handshake failures, timeouts, or authentication rejection. For a more detailed selection method, see the v2rayN first-connection guide.

When to use system proxy mode

When enabled, v2rayN points Windows proxy settings to its local listening address. Browsers and desktop programs that follow system settings send HTTP and HTTPS requests to the client, which then uses routing rules to choose direct or proxied access. For the first verification, use “Automatically configure system proxy” or the equivalent standard mode in the interface, keep the default local port, and avoid manual changes. Switching nodes normally does not require disabling the system proxy; the client applies the new active configuration to subsequent connections. Existing long-lived connections may continue on the old path, so reopen the application if necessary.

Command-line programs do not necessarily read the Windows graphical system proxy. PowerShell, package managers, and development tools each have their own proxy behavior: some read environment variables, some require separate parameters, and some use WinHTTP directly. If the browser works but the terminal does not, treat this as an application-level proxy difference rather than a sudden node failure. You can first inspect the current WinHTTP status, but do not equate it with the browser’s proxy state:

netsh winhttp show proxy

# Check whether proxy environment variables are set in the current session
Get-ChildItem Env: | Where-Object Name -Match 'proxy'

If only the current terminal session should use a local SOCKS or HTTP endpoint, set temporary parameters according to the specific tool’s documentation; they will disappear when the session ends. Do not write proxy environment variables into system-wide configuration unless you understand their scope, because those programs will still try to connect to a nonexistent local port when the client is not running. For a complete browser-versus-terminal troubleshooting path, see How to fix a system proxy that is not working.

TUN, permissions, and Windows-specific issues

TUN is useful for applications that ignore system proxies, require UDP, or need broader unified traffic capture. Before enabling it, exit other clients of the same type, grant system permission to create the virtual interface, and check the v2rayN log for interface initialization, route installation, and DNS-listener startup. If the network immediately goes offline, disable TUN and restore the system proxy to confirm that the basic connection still works. Then check for other virtual adapters, corporate networking software, game accelerators, or security tools that modify the routing table. Keep only one tool responsible for the default route.

After Windows sleep, a network change, or an abnormal client exit, the system proxy may remain enabled. The typical symptom is that v2rayN is closed while the browser continues trying to reach a local listening port. Restarting the client and closing the system proxy normally restores connectivity; you can also open Windows proxy settings and confirm that the manual proxy is off. Do not delete all network adapters or reset the entire network stack before confirming the cause, as this can affect Wi-Fi, virtualization, and corporate settings. When the log reports that a port is in use, exit duplicate instances first, then use system tools to identify the listening process:

netstat -ano | findstr LISTENING

# View the system DNS cache and record its current state before troubleshooting
ipconfig /displaydns

4. macOS: Chip Architecture, Network Permissions, and Proxy Routing

Choose the v2rayN package for your chip

When using v2rayN on macOS, start by choosing the correct architecture. Apple Silicon devices use the arm64 package, while Intel devices use the x64 package. Use the chip or processor information in “About This Mac” as the deciding factor. A mismatched architecture may prevent the app from opening or require a compatibility layer, and should not be mistaken for a subscription problem. Place the app in a standard Applications directory and avoid running it long-term from Downloads or a disk image, because configuration writes, updates, and permission records need a stable path.

The first launch may prompt you to confirm the app source or grant network permissions. Handle the prompt through Privacy & Security in System Settings instead of repeatedly copying the app and creating multiple instances. If the client opens but the kernel cannot start, check the app log for messages about a non-executable file, insufficient permissions, or an architecture mismatch. The system proxy and TUN have a usable target only after the kernel starts and creates a local listener.

Subscription management and node verification

Create a separate subscription group in v2rayN, enter the complete URL, and run a manual update. Subscription handling on macOS follows the same logic as Windows: save the source, update it, confirm the list, choose an active node, and perform a real-connection test. If the clipboard contains leading or trailing spaces or line breaks, copy a clean URL again. A subscription timeout may come from the current network, DNS, or the provider; a parsing failure is more likely to indicate a format mismatch. These errors require different responses, and the first clear log error is usually more useful than the final interface message.

Verify the connection with the system proxy before enabling TUN. The system proxy changes the proxy configuration for the current network service, so Safari and most applications that follow system network settings will use the endpoint. After enabling it, inspect the system proxy status in a terminal and confirm that the HTTP, HTTPS, or SOCKS entries point to the local address:

scutil --proxy

# View the current default system route
route -n get default

scutil --proxy only shows that the system configuration has been written; it does not prove that the node connection succeeded. Open an actual webpage and watch the client log next. If the system proxy is enabled but no application request appears in the log, check whether the app uses its own proxy, has a bypass rule, or is reusing a connection created before the proxy was enabled. Closing and reopening the app can eliminate connection-reuse interference.

System proxy settings and different network services

macOS stores settings separately for Wi-Fi, Ethernet, and other network services. After switching networks, the proxy state may need to be applied again. If v2rayN says the system proxy is enabled but the newly connected network still goes direct, turn the proxy off and on once so the client writes the configuration for the current active service. If a public network has a sign-in page, disable the proxy, complete authentication, and enable it again. Otherwise the authentication redirect may be sent through the proxy and every page may fail to load.

Terminal tools and graphical applications also differ in how they use proxies. Some commands read HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY environment variables, while others ignore the graphical system proxy. Setting variables only for the current terminal session is easier to undo and will not affect other tasks after the terminal closes. Do not write a fixed port into global shell configuration unless you have confirmed that v2rayN’s local endpoint will remain consistent and know how to disable it when the client is not running.

TUN and network-extension conflicts

When enabling TUN on macOS, the system may request network-related authorization. After granting it, check the log for successful virtual-interface creation and route installation. If the network goes completely offline as soon as the connection is enabled, common causes include another network tool still running, parallel filtering extensions, multiple programs modifying DNS, or an old interface left behind after sleep or wake. Close other traffic-capture tools and restart v2rayN before deciding whether a system reboot is needed; do not delete unfamiliar system network services.

TUN usually covers more traffic than the system proxy and can more easily affect local-device discovery, printing, and development environments. If internet access works but local-network addresses do not, check that routing rules preserve direct access to private addresses, such as whether geoip:private or an equivalent LAN rule appears before general proxy rules. Incorrect ordering sends LAN requests to a remote outbound, so local devices cannot respond. For anyone who needs local services, preserving direct LAN access should be a standard pre-flight check before enabling TUN.

If the app will not quit or the system proxy is not restored, first disable the system proxy inside v2rayN and then exit normally. If the app has already crashed, inspect the proxy settings for the current network service in System Settings. After restoring them, restart the client and run a connection test with the default settings. Only if the same issue keeps recurring should you use the logs to determine whether it involves permissions, interfaces, or the app lifecycle.

5. Linux: Packages, Desktop Proxy, Environment Variables, and TUN

Choose deb, rpm, and the processor architecture

On Linux, v2rayN requires you to confirm both the architecture and the package system. Debian, Ubuntu, and derivatives typically use deb packages; Fedora, Rocky Linux, and similar distributions typically use rpm. Choose the matching x64 package for x64 devices and the arm64 package for arm64 devices. The package manager rejects an incorrect format directly; a wrong architecture causes execution failures or unsatisfied dependencies. Before installing, use uname -m to confirm the architecture and install through the distribution’s package manager so desktop entries, dependencies, and uninstall records remain consistent.

# Example of installing a deb package; use the actual downloaded filename
sudo apt install ./v2rayN-linux-x64.deb

# Example of installing an rpm package; use the actual downloaded filename
sudo dnf install ./v2rayN-linux-x64.rpm

The commands above show only how to install local packages; use the filename actually obtained from the Download Center. If the package manager reports dependency issues, refresh the distribution’s repositories and resolve system dependencies instead of assembling shared libraries from unknown sources. After the graphical app starts, its configuration directory must be writable by the current user. Do not run the entire desktop client as root long-term. Use system authorization only for the specific operations that create TUN or modify routes.

Subscription imports and desktop-environment differences

The subscription workflow is the same as on other desktop platforms: create a group, paste the URL, save it, update it manually, and select an active node. If the app cannot read the clipboard, verify the complete URL in a plain-text editor before pasting. Wayland and X11 may handle the clipboard, tray, and windows differently, but they do not change the subscription format. A missing tray icon does not mean the kernel is not running; use the client window and process logs as the source of truth. Some desktop environments require an extension to display traditional tray items.

After updating the subscription, confirm that the server list contains entries before starting the kernel. If the log says a local port is already in use, use ss to inspect listeners. Do not terminate a system process simply because the port exists; first determine whether another v2rayN instance, a leftover kernel, or another proxy program owns it.

ss -lntp

# View proxy variables in the current user session
env | grep -i proxy

# View the default route
ip route show default

Desktop system proxy and environment variables

Linux has no single proxy setting that covers every desktop and command-line application. Desktop environments such as GNOME and KDE can store graphical proxy settings, but whether a browser reads them depends on the browser. Terminal programs commonly use environment variables or their own configuration. After v2rayN writes the system proxy, verify it first with a browser in the current desktop, then inspect terminal tools separately. A direct terminal connection does not prove that the system proxy is completely broken, and a working browser does not mean every background service will use the proxy automatically.

To make a terminal session use a local HTTP endpoint, set environment variables temporarily. For SOCKS, confirm that the target tool supports the relevant variable and DNS behavior. Use the actual listening address and port shown by v2rayN; the syntax below uses a loopback address and common local ports as an example:

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809

# Cancel after the current session ends
unset HTTP_PROXY
unset HTTPS_PROXY

If the client uses a different port, follow the values shown in its settings. Variable-name case compatibility varies by program, so understand the target tool before configuring global variables. System services usually do not inherit the user’s terminal environment, and desktop-session variables are not automatically passed to every container. When troubleshooting development tools, check the host system, container, remote session, and integrated terminal separately; do not treat multiple network namespaces as one environment.

TUN, permissions, and DNS

Linux TUN depends on a virtual network interface, routes, and permissions. Before enabling it, confirm that the system supports a TUN device and exit programs that modify the default route. When v2rayN requests elevated access, authorize only the network operation currently needed. After enabling TUN, use ip addr and ip route to observe interface and route changes. If the default route is replaced incorrectly, disable TUN in the client first and inspect again. Be especially careful on remotely managed devices, because a bad route can interrupt the current remote connection.

DNS may be managed jointly by systemd-resolved, NetworkManager, the desktop environment, or manually edited files. If domain names stop resolving after TUN is enabled while direct access to a known address still works, first check whether DNS queries reach the client, which resolver the system currently uses, and whether another network tool has overwritten the configuration. Do not permanently rewrite system resolver files to hide the problem; a network manager may regenerate them on the next connection. Define clearly whether DNS is handled by the system, the client, or a local resolver, and prevent multiple components from competing for the same listening port.

The most reliable Linux troubleshooting method is layered: first verify that the v2rayN interface and kernel run, then verify the browser through the system proxy, next test terminal environment variables, and enable TUN last. Record a clear result at each layer so you can identify whether the issue is in desktop settings, application configuration, permissions, routing, or DNS. If the log repeatedly shows timeout, rejected, or parsing errors, use the runtime log reading guide to locate the exact stage.

6. Android: v2rayNG, v2flyNG, and Per-App Routing

Choose the client and installation package

v2rayNG is the preferred Android client and follows the Xray kernel path, making it suitable for common subscriptions and routing configurations. Use v2flyNG as an alternative when you need the V2Fly kernel. Both clients capture traffic through the system VPN interface, but their kernel support, setting names, and configuration storage are not guaranteed to match. When switching clients, re-import the original subscription instead of copying the other app’s data directory. For recent mainstream devices, choose the arm64 package first; use the universal package only when the architecture is unknown or Android rejects the arm64 package.

After installation, the system displays a VPN authorization prompt on the first connection. Once allowed, the status bar shows a system-managed connection indicator. That indicator only confirms that the virtual interface exists; it does not prove that the remote node works. Verify the connection with client logs and real webpage requests. If another app already controls the system VPN interface, connecting the new client will normally disconnect the old one; two apps cannot control the same system interface simultaneously.

Import subscriptions, update them, and choose a node

In v2rayNG or v2flyNG, open subscription-group settings, add and name the complete subscription URL, save it, and run an update. Some systems restrict background network access. If an update stalls or fails immediately, keep the app in the foreground and confirm that the current network can reach the subscription source. After a successful update, a configuration list should appear. Choose one entry as the active configuration and perform a real-connection test. A QR code is suitable for importing one configuration, while a subscription is better for ongoing updates; they serve different purposes, so do not treat a single-node QR code as an automatically updating subscription group.

Latency shown in the node list is only an aid to selection. Mobile networks fluctuate significantly during cell handoffs, weak signal, and battery-saving states, so one result does not represent sustained quality. Start a connection with the selected node, open a new browser page, and immediately return to the log to see whether a real request was generated. If the log contains only interface-start messages and no outbound record, application traffic may not have entered the client. If it shows timeout, TLS, or authentication errors, traffic did enter and the problem is with the remote connection or configuration parameters.

System VPN interface and per-app routing

Android clients commonly let you choose which apps use the proxy. Two common approaches are to include only selected apps or to include most apps while excluding a few. The more complex the rules, the easier it is to miss newly installed apps. For the first setup, disable per-app routing and confirm that global capture works, then create an allowlist or exclusion list as needed. If the browser works but one app does not, check first whether that app is excluded instead of changing server parameters.

Some apps connect directly by IP, use specific UDP traffic, or ignore traditional HTTP proxies, so Android clients provide broader capture through the system VPN interface than desktop system proxies. At the same time, local-network access, casting, printing, and device discovery may be affected. To reach devices on the same network, enable LAN bypass or create direct rules for private addresses. When per-app routing and kernel routing rules coexist, the system first decides whether traffic enters the client; only then does the kernel choose an outbound. An app excluded by system-level routing will not be evaluated against kernel rules.

Background limits, battery use, and network changes

Android battery policies may restrict a client’s background operation. Typical symptoms include a connection dropping after the screen has been locked for a while, recovering when the screen wakes, or losing its status indicator after the system cleans up background apps. In system app settings, allow the necessary background activity and avoid aggressive automatic-cleanup policies. Menu names vary by device, but the test is the same: the client’s system VPN service should remain active with the screen off. Do not grant permissions unrelated to networking.

When switching from Wi-Fi to mobile data, existing connections may fail and the kernel may need to rebuild outbound connections. If recovery takes too long, stop and start the client once; there is no need to delete the subscription. If public Wi-Fi requires browser authentication, disconnect the client, complete authentication, and reconnect afterward. If Wi-Fi works but mobile data fails, check differences in mobile DNS, IPv6, and carrier access. If every node fails only on one network, the network path is more likely at fault than simultaneous failure of every subscription entry.

Before enabling a system option such as “Always-on VPN,” make sure the client is stable and understand its blocking behavior. If “Block connections without VPN” is also enabled, other apps will lose network access when the client crashes or updates. This setting is appropriate only after long-term validation, not as a first-installation default. When troubleshooting a total loss of connectivity, check the system VPN page for these restrictions so deliberate system blocking is not mistaken for a node failure.

The log entry points may differ between v2rayNG and v2flyNG, but the troubleshooting method is the same. Focus on errors around the first failure rather than the large volume of repeated messages produced by retries. When sharing logs, remove subscription URLs, user IDs, server addresses, and other sensitive data; keep only the error type, stage, and system environment. If the client says it is connected but webpages still fail, continue with the connected but no internet troubleshooting checklist.

7. Routing, DNS, and TUN: From Default Rules to Maintainable Traffic Splitting

Routing rule order

Routing determines which outbound handles a request that has already entered the client. Common outbounds are direct, proxy, and block. Rules are generally evaluated from top to bottom, and matching stops at the first hit, so specific rules should come before general ones. Handle LAN traffic and explicitly direct domains first, then use a catch-all rule to send the remainder through the proxy. If “proxy everything” comes first, later LAN-direct rules can never work. If an overly broad direct rule comes first, traffic that should be proxied may exit early.

Domain rules and IP rules address different stages. When a request initially contains only a domain, it may match geosite or an explicit domain rule. After resolution, the resulting IP can match geoip, private-address, or subnet rules. A connection may contain both a domain and a destination IP, but the information available to the client depends on the entry protocol, DNS flow, and application behavior. Do not rely on one rule to cover every case, especially because apps that connect directly by IP will not trigger domain rules. A more complete rule set usually keeps domain collections, IP collections, and a final fallback together.

A recommended basic routing structure

Start with three layers: direct access for LAN and private addresses; direct access for sites and address sets clearly belonging to the local network environment; and proxy access for everything else. Maintain block rules separately when needed rather than adding a broad domain list without checking its impact. The JSON fragment below shows the core relationships in an Xray-style routing structure. In a graphical client, you can create equivalent rules through the routing settings interface:

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "geosite:cn"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

domainStrategy controls whether IP resolution continues when domain rules do not match. IPIfNonMatch means the client tries domain matching first, then resolves the domain and tries IP rules if nothing matches. More aggressive is not always better: extra resolution increases DNS involvement, while skipping resolution entirely may prevent IP rules from matching domain requests. A graphical client may expose this parameter through a “Domain strategy” dropdown. Define the problem first, then change the setting; do not switch simply because one option appears more comprehensive.

Why DNS requests affect connectivity

DNS converts domain names into addresses. It may be handled by the system, forwarded or captured by the client, or split according to routing rules. Common failures include the system receiving an unreachable address, the client and system receiving different results, TUN capture not sending DNS queries to the expected listener, or IPv4 and IPv6 being returned in an order that does not suit the current network. Symptoms include domains failing while direct address access works, or some sites working while others keep timing out. Repeatedly switching nodes may occasionally bypass the symptom but will not repair the resolution path.

When troubleshooting DNS, answer three questions first: who receives the application’s query, which outbound sends the DNS request, and what kind of address is ultimately returned? In system-proxy mode, a browser may handle secure DNS itself or pass queries to the system. In TUN mode, the client can usually capture more queries. If the browser has an independent DNS setting, its results may bypass what the system and client expect. Start by testing with the browser’s default network settings, then decide whether custom DNS is needed. Multiple resolution schemes running at once make logs and results difficult to correlate.

Choosing between system proxy and TUN

Use the system proxy to establish the basic connection first, then decide whether TUN is necessary. If the target application already works through the system proxy, enabling TUN will not improve node quality; it only changes how traffic enters the client. Enable TUN when an application ignores the system proxy, requires UDP, or needs unified traffic management, and preserve direct LAN access. Record the current system proxy, DNS, and virtual-adapter state before enabling it so you can restore them if something goes wrong.

How to verify routing changes

Change one group of rules at a time and verify it with a clear target. After adding LAN-direct access, test both a LAN device and the internet. After changing geosite rules, check the destination domain and final outbound in the log. After changing DNS, test both a new domain and a cached domain. Do not import a large rule set, switch DNS, enable TUN, and change nodes all at once; whether it works or fails, you will not know which change caused the result.

Name routing rules by intent, such as “LAN direct,” “Common local domains direct,” and “Proxy everything else,” rather than using obscure temporary numbers. For long-term maintenance, document the purpose, matching conditions, and outbound for each rule. Subscription updates normally change server configurations, not user-defined routing. However, import behavior varies by client and may affect the current selection, so if behavior changes after an update, confirm that the active routing configuration is still correct.

8. Common Configuration Issues and Layered Troubleshooting

Locate the failing layer along the data path

Effective troubleshooting does not start with reinstalling the client. It starts by identifying where the request stops. Layer one is subscription retrieval: can it update, parse, and generate nodes? Layer two is kernel startup: can the configuration load and can the local port listen? Layer three is remote connectivity: can the node complete DNS, TCP, TLS, and protocol handshakes? Layer four is application capture: do the system proxy, environment variables, or system VPN interface send traffic into the client? Layer five is routing and DNS: after entry, does the request use the correct outbound and resolve to a reachable address? Each layer has independent evidence; find the earliest failure first.

When reading logs, focus on the time window for one operation. Clear the log or note the current position, perform one subscription update, connection attempt, or webpage visit, and then read the new entries. Repeated retries create large amounts of duplicate timeout messages that can hide the original parsing, permission, or authentication error. Among common keywords, timeout means the operation did not finish within the allotted time and may indicate an unreachable network, an unresponsive service, or slow DNS. rejected means the connection was refused by a rule, remote endpoint, or protocol condition. invalid user usually indicates a mismatch in the user ID, authentication details, or server configuration. For more detail, see How to read runtime logs.

Subscription update fails or produces no nodes

First confirm that the subscription URL is complete and was not copied from text containing a displayed ellipsis. Remove spaces and line breaks around it while preserving the original parameters. Then manually update the relevant group in the client and inspect the log. A network timeout calls for checking the current network and DNS. An unparseable response means confirming that the selected format suits the client. An empty or unauthorized response must be checked with the subscription provider. Do not add the same subscription repeatedly; that only creates multiple failed copies.

If the update reports success but the list is empty, check whether the current interface filters the group, search term, or configuration type, and confirm which group received the nodes. When migrating from another client, re-import the original subscription instead of copying its internal database. If old nodes remain after an update, the client may be configured to retain previous entries. Confirm that the new content was generated before cleaning anything, and do not delete every group without first preserving the source information.

The client starts but the system proxy has no effect

Open the client log, then send a new request from the browser. If the log contains nothing, the problem lies between the application and the local endpoint: the system proxy was not written, the browser uses independent settings, the application has not created a new connection, or the current network service did not receive the proxy configuration. If the log shows the request but the remote connection fails, the system proxy is working and the investigation should move to the node, DNS, or routing. This approach prevents proxy-capture issues from being confused with server problems.

On Windows and macOS, open system network settings to confirm the proxy state. On Linux, check desktop proxy settings and terminal environment variables separately. On Android, check system VPN authorization and per-app routing. A terminal tool not following the browser’s proxy is a common mechanism difference; check the parameters supported by that tool. If the network fails after the client exits, look for a leftover system proxy or a “Block connections without VPN” setting. Continue with separate checks for browsers and command-line terminals.

The client says connected but webpages will not open

“Connected” usually means only that the kernel or virtual interface has started. First switch to a node that has passed a real-connection test and verify the device time and time zone. Next check whether webpage requests appear in the log, then inspect DNS errors and whether routing sends requests to the expected outbound. Finally check for conflicts between the system proxy or TUN and other network tools. If every node fails on the same device and network while another network works, investigate the current network path first. If only one node fails, its configuration or remote status is more likely responsible.

Do not treat a Ping result as the final verdict. A server may not answer ordinary probes while its proxy protocol still connects; conversely, a responsive address does not prove that authentication and TLS handshakes succeed. A real-connection test and an actual webpage request better reflect the usage path. See the complete v2rayN and v2rayNG troubleshooting checklist, organized around nodes, time, DNS, routing, and the system proxy.

The network drops or LAN becomes unreachable after enabling TUN

Disable TUN in the client immediately and check whether basic connectivity returns. If it does not, inspect the system proxy, system VPN blocking options, and leftover virtual interfaces. Once the basic network is restored, keep only the current client active, close other programs that modify routing or DNS, enable TUN again, and watch the first error. Permission problems usually occur while creating the interface; port conflicts occur while starting the listener; default-route or DNS errors commonly appear as request timeouts after the interface has been created.

If the internet works but the LAN is unreachable, check that private-address direct rules exist before the fallback proxy rule. Common private and local-link addresses should not be sent to a remote outbound. On Android, also check LAN bypass in the app settings. On desktop platforms, confirm that the firewall has not placed the new virtual interface in an unsuitable network scope. After making changes, test both a LAN address and a normal domain; validating only one is not enough.

Port conflicts, duplicate instances, and configuration rollback

When the log says an address is already in use, another client instance, leftover kernel process, or proxy program usually owns the same port. Identify the owner through Task Manager, Activity Monitor, or the process list, then exit the relevant program normally. Changing the port may let the current instance start, but system proxy settings, environment variables, and application-specific fixed values must also be updated, creating new inconsistencies. Resolve duplicate instances first and change the port only if necessary.

If the problem began after a settings change, the most effective response is to undo the latest item rather than restore the entire configuration. Disable TUN, custom DNS, newly added routes, and per-app routing in reverse order, while keeping the subscription and one node. Add items back one at a time after the basic connection returns. If the client configuration is difficult to assess, record the subscription source and create a new minimal configuration for comparison. If the new configuration works, the old preferences conflict; if it also fails, continue checking platform permissions, the network, and subscription content.

Final checklist

1. The installation package matches the platform, processor architecture, and distribution format.
2. The subscription group updates manually, the node list is not empty, and no filter is hiding it.
3. The active node passes a real-connection test, and the system time and time zone are correct.
4. The kernel starts successfully, and the local listening port is not occupied by a duplicate instance.
5. Requests from the browser or target application appear in the client log.
6. Routing rules are ordered from specific to general, with direct access preserved for LAN and private addresses.
7. DNS has one clearly defined handling path, with no multiple tools overriding it at the same time.
8. TUN is enabled only after the basic system-proxy test succeeds, and it can be disabled to restore connectivity if needed.

If these checks still do not reveal the cause, narrow the issue to one platform, one client, one subscription group, one node, and one traffic-handling method, then record the complete reproduction path. Explaining “which step fails” and “what appears in the log” is far more useful than simply saying “cannot connect.” To repeat the shortest workflow, return to the quick-start guide. To choose a different package or confirm the platform entry point, visit the Download Center.