Complete v2rayN Installation and Configuration Guide for Windows, macOS, Android, and Linux

// 01 · PREPARE

General prerequisites and configuration boundaries

Before installing the client, confirm the platform, CPU architecture, subscription source, and traffic scope. Most installation failures come from choosing the wrong package, an old process holding a port, an incorrect system clock, or parameters that do not match the server—not from the client itself. Fixing these variables first makes the workflow on all four platforms much clearer.

Client and platform mapping

Use v2rayN on desktop platforms. It supports Windows, macOS, and Linux with graphical controls for subscription groups, server lists, system proxy, TUN, routing rules, and logs. On Android, v2rayNG is the preferred option and uses the Xray core; choose v2flyNG when the v2fly core is required. The two Android clients have similar layouts and import workflows, but their core capabilities, experimental options, and configuration compatibility can differ. The same advanced configuration should not be assumed to be fully interchangeable.

The installer architecture must match the device CPU. On Windows, x64 is common; on macOS, first identify Apple Silicon or Intel; on Linux, choose deb or rpm in addition to the CPU architecture; most recent Android phones use arm64, with the universal package as a fallback when the architecture is uncertain. The installer page separates downloads by platform and architecture, so there is no need to guess from a file-name list.

Platform	Preferred client	Package selection	Primary traffic handoff
Windows	v2rayN	x64 desktop or classic WPF edition	System proxy, TUN
macOS	v2rayN	Apple Silicon arm64 or Intel x64	System proxy, TUN
Linux	v2rayN	deb / rpm with x64 / arm64	Desktop proxy, environment variables, TUN
Android	v2rayNG	arm64 or universal edition	System VPN interface

Subscriptions, individual nodes, and local configuration

A subscription URL is a remotely hosted node list that can be refreshed. After saving the URL, the client pulls server names, protocols, ports, and transport parameters into a subscription group. Individual share links are useful for temporary imports or testing one parameter set; local JSON configuration is better for detailed routing, multiple outbounds, and complex DNS policies. Each method serves a different purpose. For everyday use, keep nodes in subscription groups so updates do not require manual re-entry. For advanced rule testing, copy the current configuration into a separate group so experiments cannot overwrite a stable setup.

A subscription URL usually contains access credentials and should be handled like account information. Never paste the complete URL into public logs, screenshots, or online conversion pages. Before using a V2Ray subscription converter, verify the service source and output format, then check that key fields such as protocol, security, network, flow, SNI, and public key are preserved. Conversion only changes the representation the client can read; it does not automatically resolve parameter differences between the server and client.

Pre-connection environment checks

First, synchronize the system date, time, and time zone. TLS and REALITY handshakes depend on a valid time window, so a significant clock error can look like a node that always times out. Next, quit older clients and make sure no other process owns the local proxy port. Check that security software and the system firewall allow the client and core to create local listeners and external connections. Finally, prepare a subscription URL that is reachable and confirm the account status, traffic allowance, and expiry date. Seeing node names only proves that the subscription was read; it does not prove that a node is currently reachable.

Validate a connection in three layers: whether the core starts, whether the local proxy port is listening, and whether application traffic enters the proxy. Checking only whether a webpage opens makes the failing layer difficult to identify. If the log says startup completed but the browser produces no traffic, check the system proxy or the browser's own proxy settings. If no local port appears, investigate configuration parsing, port conflicts, or core-file permissions first. If the failure occurs during the handshake, return to the server parameters and local clock.

Update and backup principles

Before updating the client, export or back up subscription groups, custom routes, DNS rules, and local configuration. On desktop, also record the current system proxy mode and local listening ports. During a major UI-generation upgrade, older configurations can usually be migrated, but default values may change, so review the core settings page by page after the first launch. On Android, make sure the subscription URL is still accessible before updating; do not rely only on the temporary node list already expanded inside the app.

The remaining chapters follow the same validation order: start the client after installation, import and update the subscription group, select a node and start the core, choose system proxy or TUN, then check the logs and actual traffic. Keeping this order fixed avoids changing several variables at once. If you need to finish the first setup in ten minutes, open the v2rayN Getting Started guide; if you want to understand each setting, continue with the chapter for your platform.

// 02 · WINDOWS

Windows: v2rayN installation, subscriptions, and system traffic handoff

Windows offers the most complete v2rayN workflow. During installation, choose between the desktop and classic WPF editions; after connecting, select system proxy or TUN based on the applications that need coverage. The two interfaces are implemented differently, but their core concepts—subscriptions, nodes, routing, and core logs—are the same.

Choose the desktop or classic WPF edition

The desktop edition uses a newer cross-platform interface and suits users who want a similar workflow across desktop operating systems. The classic WPF edition retains the familiar Windows layout for users accustomed to traditional server lists, tray menus, and settings. Do not run both at the same time. For comparison testing, quit the first client completely and confirm that it restored the system proxy; otherwise the second client may take over the same ports, making log and traffic sources unclear.

Get the appropriate package from the Windows installer page and complete the setup wizard. If Windows asks about network access or the firewall on first launch, allow the client to communicate on the network type currently in use. The installation and user configuration directories need normal read/write access. Managed devices may restrict proxy settings, virtual adapters, or driver installation; those limits must be handled by device policy. Reinstalling the client repeatedly cannot bypass system-level restrictions.

Import subscriptions and organize groups

Open subscription group management, add a clearly named group, enter the subscription URL, and save it. Then update the current group. After a successful update, nodes appear in the server list. If the group exists but the list is empty, check the log for the HTTP status, parsing errors, or format messages. Avoid clicking update repeatedly in quick succession because some subscription services limit request frequency. A change in node count reflects a server-side list update; the client does not create nodes by itself.

Keep key columns such as name, address, port, protocol, transport, security layer, and subscription group visible in the server list. When choosing a node, do not rely only on a region or route label in its name; make a real connection and watch the handshake log. Latency tests describe reachability under that specific test method and do not cover every path used by the target application. Once a stable node is confirmed, make it the active server and then enable system proxy or TUN.

To import an individual node manually, read a standard share link from the clipboard or enter each field in the server editor. For REALITY nodes, pay particular attention to serverName, fingerprint, publicKey, shortId, and flow. If an imported share link still fails, compare every field with the server-provided details instead of randomly switching security options.

When to use system proxy mode

System proxy mode suits browsers and desktop applications that follow Windows proxy settings. Once enabled, v2rayN points the system proxy to its local listening address and port, and applications send traffic through the client. Start by keeping “Automatically configure system proxy” or its equivalent enabled, then test in a browser. If a program ignores the system proxy, specify an HTTP or SOCKS address inside that program or use TUN instead.

The system proxy routing mode determines which destinations enter the proxy. Global mode is convenient for a short node test but is not a good final setup for complex split routing. Rule mode uses domain, IP, geosite, and geoip rules to choose direct, proxy, or block outbounds. After changing the mode, start a new connection; existing long-lived connections may continue using the old path. Restoring the system proxy before quitting is good practice, especially on devices that frequently switch networks or wake from sleep.

TUN mode and permissions

TUN uses a virtual network interface to handle a wider range of traffic. It is useful for applications that ignore system proxy settings, command-line tools, and scenarios requiring unified routing. First-time activation usually needs administrator permission and may install a virtual adapter or network component. Quit other similar networking tools before enabling it to prevent multiple virtual interfaces from changing the default route. After activation, check TUN status, DNS listeners, and routing logs to confirm that traffic is entering the current core.

TUN does not make every connection work automatically. Local-network access, virtual machines, development containers, remote desktops, and corporate intranets may depend on specific routes. If local devices become unreachable, send private address ranges directly and check strict routing, auto-routing, and DNS hijacking settings. If the network does not recover immediately after disabling TUN, fully quit the client first, then disable and re-enable the current network adapter. Do not reset every network setting before locating the problem.

Logs, tray controls, and startup behavior

v2rayN's main log shows configuration generation, core startup, local ports, and errors. When troubleshooting, clear the old log first and reproduce the issue once so errors from a previous node are not mistaken for current results. Common items include port conflicts, unparseable configuration fields, failed DNS requests, connection timeouts, and interrupted handshakes. If the log shows the core started normally, check the system proxy and routing next. If the core keeps exiting, return to the configuration file and permissions.

The tray menu usually provides quick controls for the system proxy, active server, and exiting the application. Closing the main window does not always terminate the process, so explicitly quit from the tray when changing versions or investigating a port. Before enabling launch at startup, confirm that the default node, subscription update behavior, and traffic handoff mode are appropriate. On portable devices that switch between home, office, and mobile hotspots, keep a manual confirmation step for the handoff mode so an unsuitable route is not reused after login.

// 03 · MACOS

macOS: chip selection, permissions, and proxy configuration

The macOS edition of v2rayN shares its main features with other desktop editions, but the package must match the CPU architecture. First launch may also involve app approval, network configuration, and TUN permissions. Handling system-level permissions first and node or protocol issues second avoids unnecessary reinstalls.

Identify the CPU and complete installation

Open System Information or “About This Mac” to check the chip name. If it shows Apple silicon, choose the arm64 package; if it shows an Intel processor, choose the x64 package. The wrong architecture may prevent launch or rely on compatibility translation with unstable behavior. Download the matching DMG from the macOS installer page, open it, and follow the window prompt to move the app to Applications before launching it from there.

On first launch, macOS may ask you to confirm the app source or network access. Complete the confirmation through the security prompt in System Settings instead of repeatedly copying the app to different folders. Multiple copies make the configuration location, login item, and running version difficult to identify. If the old interface still appears after an update, use Activity Monitor to confirm that the old process has ended, then launch the new copy from Applications.

Import subscriptions and choose a server

Open subscription management, create a group, save the subscription URL, and update the group. Once nodes appear, choose a server with clearly defined parameters as the active node. If the update fails, check whether the current network can reach the subscription URL, whether the URL was copied in full, and whether the system date is correct. If the link contains special characters, paste it exactly as provided; do not remove query parameters.

Node parameter checks on macOS are the same as on Windows. For VLESS, check the user ID, encryption fields, transport layer, and flow. REALITY also requires serverName, fingerprint, publicKey, and shortId. WebSocket or gRPC settings must retain the same path, host name, or serviceName. A node working on another device only proves that the server is broadly reachable; the import on this device may still be missing fields.

System proxy and application differences

When system proxy is enabled, v2rayN changes the proxy configuration for the current network service. Most browsers and applications that use the system networking framework will follow it. Command-line programs, development tools, and some cross-platform apps may read their own proxy environment variables or bypass the system proxy entirely. Check the client log as well: open the target app and make a new request. If no connection appears, the traffic has not reached v2rayN.

A temporary terminal proxy can explicitly point to v2rayN's local HTTP listening port. Use the value shown in the client's settings; the example below uses a common local address only to demonstrate the environment-variable syntax:

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

# Not retained after the current terminal session ends
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Do not add the example permanently to your shell configuration until the port is confirmed. If the client port changes later, old environment variables will keep sending terminal traffic to an inactive port. For long-term use, keep the port record synchronized with v2rayN settings and explicitly unset the proxy variables when the client is closed.

TUN, DNS, and system authorization

TUN is useful for applications that do not follow system proxy settings. On first activation, macOS may request administrator approval or permission for a network extension. After approval, check the menu-bar network status and v2rayN log to confirm that the virtual interface was created. If other tools modify routes or DNS, quit them first and keep only one traffic handoff service active. When several tools write the default route, symptoms can include intermittent webpage access, broken LAN connections, or DNS request loops.

DNS settings need to be understood together with routing. Resolving a domain before matching its IP can produce a different result from matching a domain rule directly. If using FakeDNS, confirm that the target application and LAN services are compatible with this mapping approach. For the boundaries of retained address mappings and TUN scenarios, read How FakeDNS virtual DNS mapping works. When LAN printing, file sharing, or development-device discovery fails, first send private addresses and local domains directly, then temporarily disable advanced DNS features for comparison.

Sleep, network switching, and clean exit

After a laptop wakes from sleep or switches Wi-Fi networks, existing connections, the DNS cache, and the default route may no longer be valid. Stop the current connection, select the node again, and start it. If the system proxy still points to the right place but no traffic flows, restarting the core is usually more effective than reinstalling the client. When switching from a company network to a home network, also check whether direct rules created for the intranet still fit the current environment.

Before quitting v2rayN, disable the system proxy or TUN so macOS can restore the normal network path. If the network is abnormal after force-quitting, open network settings and check whether the current service's HTTP, HTTPS, and SOCKS proxies still point to a local port. Remove the stale entries rather than deleting the entire network service. A working app, a running core, and a restored system proxy are three separate acceptance checks for a completed macOS installation.

// 04 · LINUX

Linux: package installation, desktop proxy, and TUN

The Linux edition of v2rayN targets desktop environments. Installation requires checking both the distribution's package system and the CPU architecture. At runtime, distinguish desktop proxy settings, terminal environment variables, and TUN as three separate traffic entry points. Menu names vary by distribution, but the troubleshooting logic is consistent.

Choose deb, rpm, and the CPU architecture

Debian, Ubuntu, and common derivatives generally use deb; Fedora, Rocky Linux, and AlmaLinux use rpm. For common desktop x86-64 hardware, choose x64; for arm64 devices, choose the matching architecture. Use the following command to confirm the architecture and system information:

uname -m
cat /etc/os-release

x86_64 usually maps to x64, while aarch64 usually maps to arm64. After confirming, choose a package from the Linux installer page. Do not infer the package format from the desktop appearance, and do not force a package for another architecture onto the current system. When the package manager reports dependency issues, refresh the distribution's repository metadata first, then let the package manager resolve dependencies.

Install with the package manager

In the download directory, give deb packages to apt and rpm packages to dnf. Use the actual downloaded file name; the commands below demonstrate installing a clearly specified package from the current directory:

# Debian / Ubuntu family
sudo apt update
sudo apt install ./v2rayN-linux-x64.deb

# Fedora / Rocky Linux family
sudo dnf install ./v2rayN-linux-x64.rpm

Using the package manager instead of merely extracting files keeps the desktop entry, dependencies, and uninstall record consistent. Launch v2rayN from the application menu after installation. If the terminal says no display environment is available, the session may not be inside a graphical desktop; v2rayN is a graphical client and should not be treated as a headless server service. In a remote desktop session, also confirm that the user has a graphical session and write access to the user configuration directory.

If the application exits immediately after launch, start it once from a terminal and read standard error while checking the user log directory. Common causes include missing graphics-library dependencies, a package for the wrong architecture, configuration-directory permissions, or an old process still running. Do not run the entire client permanently as an administrator to work around permissions; that changes ownership of user configuration files and grants unnecessary privileges beyond TUN.

Subscription management and the desktop system proxy

Create a subscription group, paste the URL, save it, and update the group. Once the node list is generated, select an active server and start the core without enabling TUN yet. Use the client log to confirm that local HTTP and SOCKS listeners are established, then configure the system proxy in v2rayN. GNOME, KDE, and other desktop environments store proxy settings differently. Some applications read the desktop proxy while others read only environment variables, so one browser cannot represent the entire system.

After enabling the desktop proxy, check in system settings that HTTP, HTTPS, and SOCKS point to the local machine. Set environment variables for terminal tools when needed, using the current listening port. A graphical program launched from the desktop menu may not inherit terminal variables, while a program started from the same terminal usually will. During troubleshooting, record which session launched the application so correct-looking variables are not mistaken for variables the process actually read.

TUN, capability authorization, and routing

Linux TUN creates a virtual interface, writes routes, and handles DNS, so these operations require system privileges. Prefer the authorization flow provided by the client instead of granting the entire program permanent administrator access. Before enabling TUN, check for existing VPN interfaces, container networks, virtual-machine bridges, or policy routes. Developer workstations often have more complex network topologies than ordinary desktops; automatic routing can affect container-to-host access, LAN service discovery, or remote maintenance connections.

After enabling TUN, use ip address and ip route to inspect interface and route changes, and use the v2rayN log to determine whether traffic reaches the core:

ip address
ip route
ss -lntup | grep -E '10808|10809'

The port in the final command is only a common example; replace it with the port currently used by the client. If the TUN interface exists but domains cannot be resolved, check the DNS listener, system resolver, and network-management service used by the distribution. If IP connections work but domains fail, focus on DNS. If no destinations produce log entries, check whether the default route enters the virtual interface. If only LAN traffic fails, add a direct rule for private addresses.

Updates, removal, and configuration directories

Before updating with a new package, quit v2rayN and back up subscriptions, custom routes, and DNS settings. Install the new package with the same package manager; user configuration is normally retained. After updating, verify the local ports and traffic handoff mode on the first launch. If the old process is still running, the new program may fail because of a configuration lock or port conflict. Check the system monitor or process list before deciding whether to terminate it.

Removing a package and deleting user configuration are separate operations. When the package manager removes the application, configuration in the user directory may remain for later recovery. Do not delete the entire configuration directory at the start of troubleshooting, because that also removes logs and rules that could identify the issue. A safer approach is to export the configuration, close the program, rename the existing configuration directory, and launch a clean environment for comparison. If the clean environment works, migrate subscriptions and rules back one at a time to locate the trigger.

// 05 · ANDROID

Android: v2rayNG imports, connections, and per-app routing

v2rayNG is the preferred Android client and uses the Xray core; v2flyNG is the alternative for the v2fly core. Mobile traffic is handled through the system VPN interface rather than a desktop system proxy. Permissions, battery policies, background restrictions, and per-app routing are the main differences from desktop platforms.

Choose an arm64 or universal package

Most recent Android phones use arm64. Use the universal edition only when the device architecture is unknown or the arm64 package cannot be installed. Both v2rayNG and v2flyNG provide the relevant options; see the Android installation page for the order and architecture details. When switching clients on the same device, stop the current connection first so the system VPN interface is not still held by the other app.

On first launch, the client asks to create a VPN connection when you connect. The system can route current traffic through only one connection of this type, so another VPN app may override authorization or disconnect it immediately. If no status icon appears after tapping connect, check whether system authorization is complete and whether device-management policy is blocking it.

Import subscriptions and share links

Open subscription settings, add a group name and subscription URL, save them, and update the group. If an update fails on mobile data, test again on a stable Wi-Fi network; if both fail, check the subscription URL, account status, and log. After a successful update, return to the main list, select a node, and tap Connect. Avoid switching apps repeatedly or clearing the background during an update, as this can interrupt downloading and parsing.

Import an individual node from a standard share link in the clipboard or scan a QR code from a trusted source. After importing, open the editor and verify the server address, port, user ID, transport, security layer, and SNI. A QR code is only an encoding format and cannot determine whether the parameters match. For REALITY nodes, also verify fingerprint, publicKey, shortId, and flow; missing fields can still be saved while the handshake fails.

A subscription update usually replaces the remote nodes in a group. Copy long-term manual edits to a separate group so the next update cannot overwrite them. Node names are labels only; changing one does not change connection parameters. For a long list, manage nodes by subscription group instead of mixing multiple sources at the same level.

Routing modes and per-app routing

Choose a suitable routing mode before connecting. Global mode is useful for verifying the current node; rule mode selects proxy or direct access by domain and IP; custom configuration suits users who need detailed DNS, multiple outbounds, or a specific rule order. For the first setup, use a simple mode to confirm connectivity, then add rules gradually. Enabling complex DNS, per-app routing, and multiple route groups at once makes the source of a failure difficult to identify.

Per-app routing specifies which applications use v2rayNG or excludes apps that clearly need direct access. Consider the relationship between system components, the browser, and the target app. For example, an app may open an external browser to complete login; if they use different paths, the callback can fail. After changing the app list, disconnect and reconnect so the system VPN interface is rebuilt with the new rules.

LAN devices, casting, printing, and file transfers usually need private addresses to bypass the proxy. If LAN features stop working after connecting, first check bypass-LAN or private-address rules, then see whether local domains are being sent to a remote resolver. Rule order matters too: specific direct rules must come before broad proxy rules that would match them first.

Battery optimization and background stability

Some devices restrict v2rayNG when the screen is off, the battery is low, or the app stays in the background for a long time. The connection icon may remain visible while traffic stops, then resume when the app is reopened. In system battery settings, allow the client to run as needed and ensure background data is not restricted. Menu names vary by manufacturer; the goal is to prevent the system from freezing the client or core during a connection.

Stability testing should cover foreground browsing, recovery after the screen turns off, and switching between Wi-Fi and mobile data. A network switch changes the local address, DNS, and default route, so a brief reconnect is normal. If the connection never recovers, disconnect and reconnect, then check whether the log stops at DNS, the handshake, or system VPN creation. Do not judge connection quality solely by the status-bar icon: it shows that the interface exists, not that the target node completed its handshake.

Switching boundaries between v2rayNG and v2flyNG

v2rayNG is the preferred Android client for Xray core capabilities and related protocol configurations. v2flyNG uses the v2fly core and is an alternative for specific configuration requirements. Before switching clients, export or save the subscription URL; do not assume they share an internal app database. The same subscription usually expands to similar basic nodes in both clients, but advanced fields, experimental features, and defaults may differ.

For a comparison, keep the node, network, and routing mode the same and change only one variable at a time. If v2rayNG connects but v2flyNG does not, check whether the configuration uses fields the latter does not currently process; reverse the check for the opposite case. The goal is not to keep switching cores, but to confirm that the subscription format, protocol parameters, and client capabilities match.

// 06 · ROUTING

Subscriptions, system proxy, TUN, and routing rules

The interfaces differ across all four platforms, but the core data flow is the same: the application sends a request to a local proxy or virtual interface, the core selects an outbound according to routing rules, and then establishes a connection using the node protocol. Once this order is clear, system proxy, TUN, DNS, and subscriptions are no longer isolated switches.

What a subscription update actually changes

A subscription update mainly changes the server list and connection parameters; it should not rewrite every local preference. The client normally places remote nodes in the matching group while retaining local routes, system proxy mode, and some UI settings. Subscription formats differ in how they represent groups, tags, and advanced fields, so conversion may drop fields or change names. After changing subscription formats, inspect at least one node's protocol, security layer, transport, and flow instead of merely confirming that the list appears.

Keep multiple subscription sources in separate groups. Groups make updates easier and prevent same-named nodes from becoming difficult to trace. Before deleting a group, confirm whether the active server belongs to it. If an update removes the active node, the client may keep an old cache or require a new selection. When a connection suddenly fails, update the current subscription and select a node that still exists before investigating more complex network issues.

Choosing between system proxy and TUN

A system proxy works when an application actively reads the proxy address and connects to the local port. Its boundary is clear and its impact on system routing is limited, making it suitable for browsers and standard desktop applications. TUN takes over traffic at the network layer, covers more applications, and suits programs without proxy support or unified routing requirements. They do not need to be combined for extra power. In most cases, choose one primary entry point; using both increases the effort needed to diagnose loops and duplicate handoffs.

Item	System proxy	TUN
Coverage	Traffic from applications that follow system or app proxy settings	Traffic entering the virtual interface and matching routing rules
System impact	Primarily changes proxy settings	Involves the virtual interface, routes, and DNS
Best for	Browsers, standard desktop apps, and command-line tools configured separately	Apps that ignore proxies, unified routing, and app-level handoff
Troubleshooting focus	Local ports, app proxy settings, and leftover system proxy entries	Permissions, default routes, private ranges, DNS, and interface conflicts

Routing match order

Routing rules are generally evaluated in order. Once a rule matches, traffic is sent direct, through a proxy, or to a block outbound. Specific domains, address ranges, and LAN rules that must remain direct should come before broad rules. A common structure is direct access for private addresses, selective routing for defined domain sets, and a default outbound for everything else. More rules do not necessarily mean more accurate results; duplicate sets and overlapping conditions make actual matches harder to predict.

domainStrategy controls whether the client resolves an IP when a domain rule does not match directly. IPIfNonMatch means that if no domain rule matches, the client resolves the domain and then tries IP rules, balancing domain matching with an IP database. Relying entirely on IP rules gives DNS more influence over the result. The following routing object can be merged into an Xray root configuration; outbound tags must match those actually defined in the current configuration:

{
  "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"
      }
    ]
  }
}

The final rule in the example is a fallback and should come after specific rules. If the configuration also blocks ads or routes development domains and specific services directly, place those rules before the fallback. For geosite and geoip combinations, match order, and the three-part template, see Practical split routing with routing rules.

DNS, FakeDNS, and leak paths

DNS turns domain names into addresses and also affects the order in which domain and IP rules are evaluated. In system proxy mode, an app may resolve names itself or hand them to the proxy; with SOCKS, the chosen mode determines whether resolution occurs locally or remotely. TUN usually centralizes DNS handling, but browser secure DNS, app-level resolvers, and LAN name services still matter. During troubleshooting, identify who resolves the request before choosing a DNS server.

FakeDNS creates domain mappings with reserved addresses, allowing the core to recover the original domain during a later connection. It can reduce some resolution round trips and preserve domain information in TUN, but it is not suitable for every app. Applications that require real IPs, LAN discovery, certain peer-to-peer flows, or their own validation of DNS results may behave unexpectedly. Keep a standard DNS configuration as a fallback so you can compare quickly instead of changing routing and nodes at the same time.

Checking REALITY and transport parameters

REALITY is commonly used with VLESS nodes. The client must accurately retain the server address, port, user ID, serverName, fingerprint, publicKey, shortId, and flow. xtls-rprx-vision must match the server configuration and node protocol. network is normally determined by the server; do not switch randomly between tcp, WebSocket, and gRPC simply because a connection fails.

When a handshake fails, verify the fields first, then check the system clock and basic reachability. If the log shows that the server port was reached but the connection ended during the security handshake, the local proxy and network path are broadly working; focus on SNI, public key, shortId, fingerprint, and flow. If the server port cannot be reached at all, check the address, port, current network, and node status first. Layered diagnosis is more effective than repeatedly changing client settings.

Validation after configuration changes

After changing a subscription, route, or DNS setting, stop the connection and restart the core. Clear the log and test one destination that should be direct, one that should use the proxy, and one LAN destination. Check that the outbound tags match expectations. Testing one webpage cannot prove that split routing is complete because it may involve multiple domains, connection reuse, and cache.

After validation, record the client, subscription group, active node, traffic handoff method, and custom rules. Desktop and Android can share server parameters through the same subscription, but system proxy, TUN, and per-app routing must be configured separately on each device. Separating node configuration from device traffic-handoff settings is the key to stable cross-platform use.

// 07 · TROUBLESHOOTING

Common configuration issues and a fixed troubleshooting order

The key to troubleshooting is identifying the failing layer before changing its variables. Recommended order: system time and network, subscription and node, core startup, local listener, traffic handoff, DNS, then routing rules. With a fixed sequence, most issues do not require reinstalling the client.

Step 1: Confirm the basic network, time, and subscription status

With client traffic handoff disabled, first confirm that the current network can reach ordinary sites, then synchronize the date, time, and time zone. Corporate networks, public Wi-Fi, and mobile hotspots may apply different port policies, so a node working on one network and timing out on another is not contradictory. Next check that the subscription is still valid, the account has not expired, and traffic remains available, then update the subscription once.

If the subscription update itself fails, the problem occurs before node connectivity. Check the HTTP status, timeout, or parsing details in the log, and confirm that the full subscription URL is reachable from the current network. Do not modify protocol fields at this stage because the client has not obtained the new configuration. If the node list updates but every connection fails, continue to the next step.

Step 2: Check node parameters and server reachability

Choose a node with clear parameters and verify the address, port, protocol, user ID, security layer, and transport one by one. For REALITY, also check serverName, fingerprint, publicKey, shortId, and flow. For WebSocket, check path and host; for gRPC, check serviceName. After subscription conversion, pay special attention to whether advanced fields were preserved.

A timeout in the log only means that the current step did not finish within the allowed time; it does not identify a single cause. A timeout before reaching the server may indicate name resolution, an unreachable port, or a restriction on the current network. If TCP connects but the handshake times out, focus on the security layer and server status. If the connection closes quickly, parameters may not match or the server may be rejecting it. Follow the six-step node timeout checklist for a structured comparison.

Step 3: Confirm core startup and local ports

Clear the log, stop the connection, and start it again. Look first for configuration loading and core startup results, then confirm that local HTTP, SOCKS, or TUN listeners are established. If the address is already in use, quit other clients or change the conflicting port. Closing a window does not always end a background process, so check the tray, Activity Monitor, system monitor, or app list.

Configuration parsing errors usually identify the field type, unknown option, or JSON position. For custom JSON, restore the client-generated baseline first and merge custom sections back one at a time. JSON cannot contain comments, and arrays or objects cannot end with trailing commas. Only after the core runs continuously should you investigate system proxy and traffic handoff.

Step 4: Determine whether application traffic reaches the client

After starting the node, open the target application and make a completely new request while watching the access log. If there is no record at all, traffic has not reached the client. On desktop, check that the system proxy is enabled, the app is not using its own proxy, and terminal environment variables are correct. On Android, check VPN authorization and per-app routing. With TUN, check the virtual interface and default route.

If the log records a connection but the target behaves incorrectly, the entry point is working; continue with outbound, DNS, and routing checks. Browsers may reuse old connections, so close relevant tabs or restart the browser before testing. Some apps have their own DNS and proxy settings and must be checked separately rather than inferred from system settings.

Step 5: Separate DNS and routing issues

If domains fail while direct IP connections work, check DNS first. Determine whether the DNS request reaches the core, which server handled it, whether browser secure DNS bypassed it, and whether FakeDNS suits the application. If DNS returns an address but traffic takes the wrong outbound, check domainStrategy, rule order, and geosite or geoip matching.

When only some sites fail, record the failing domains and the rules they match instead of switching to global mode permanently. Global mode can prove that the node works overall, but restore rule mode afterward and correct the specific conditions. For LAN failures, verify direct access for private addresses first. For local-domain failures, check the system search domain and whether local DNS has been overridden.

Symptom	Check first	Next step
Subscription will not update	URL integrity, account status, current network, and log output	Test on another network; do not modify node fields
Core exits immediately after startup	Configuration parsing, port conflicts, and file permissions	Restore the baseline configuration and restart
No browser log entries	System proxy, app-specific proxy, and local port	Create a new connection and watch the access log
LAN stops working after TUN is enabled	Private ranges, automatic routing, DNS, and other virtual interfaces	Add a direct rule and test separately
REALITY handshake fails	Time, SNI, public key, shortId, fingerprint, and flow	Compare every field with the server configuration
Transmission stops after switching networks	Old connections, default route, and background restrictions	Stop the core and establish a new connection

Platform-specific recovery actions

After a forced exit on Windows, check whether the system proxy still points to an inactive local port and confirm that the old process has ended. If the network does not recover after TUN, quit the client first, then re-enable the current network adapter. On macOS, check proxy entries for the current network service and virtual-network authorization; do not delete the entire network configuration. On Linux, inspect virtual interfaces, the default route, DNS services, and listening processes, preserving the management return path on remote devices. On Android, check whether the system VPN is still held by the old app, whether battery policy has frozen the background process, and whether reconnection completed after the network switch.

These recovery actions address leftover system traffic handoff; they do not repair node parameters. If the client still cannot connect after normal networking is restored, return to the relevant log layer. Reinstall repeatedly only removes context and cannot change subscription status, server parameters, or current network conditions. Reinstall only after confirming damaged application files or a failed upgrade migration.

How to collect useful logs

When submitting or saving troubleshooting notes, include the platform, client name, traffic handoff method, protocol type, time of failure, steps taken, and relevant error lines. Hide subscription URLs, user IDs, public keys, other account credentials, and complete share links. Capture logs from one complete reproduction after clearing the old records so multiple nodes and startup attempts are not mixed together.

A useful report might read: “Windows with v2rayN in system proxy mode; subscription update succeeded and the core is listening; browser requests appear in the log, but the REALITY handshake fails after selecting the active node.” This already rules out the subscription, core, and traffic-entry layers. “It doesn't work” does not show where to begin. For more common questions, open Troubleshooting, organized into fundamentals, installation and configuration, usage tips, and troubleshooting.

Create a stable configuration you can roll back to

After resolving an issue, record the subscription group, active node, routing mode, DNS policy, local ports, and platform permissions. Save a separate baseline of custom configuration and make future changes from a copy. Back up desktop configuration before updates, and keep the subscription source and key node parameters on Android. A stable configuration is valuable not because it never changes, but because every experiment can quickly return to a verified state.

Full acceptance testing should cover startup, subscription updates, node handshakes, system traffic handoff, direct rules, proxy rules, LAN access, and network switching. Button locations vary across the four platforms, but the reasoning is the same: confirm the data source, then the core, then the traffic entry point, and finally DNS and the outbound. Maintaining this order keeps larger configurations diagnosable at a specific layer.