v2rayN Setup and Configuration Guide

Prepare for installation and choose a client

Confirm the platform, processor architecture, and coverage needed

Before installing, answer three questions: Which operating system does the device run, what processor architecture does it use, and which apps need network access through the client’s local proxy? The platform determines the package format, the architecture determines whether the binary can launch, and the coverage required determines whether to use a system proxy or TUN. For desktop systems, v2rayN is the preferred choice; it supports Windows, macOS, and Linux and provides subscription management, core switching, routing rules, and system proxy controls. On Android, v2rayNG is the preferred option. Use v2flyNG when a configuration specifically requires V2Fly core behavior or must remain consistent with an existing V2Fly setup.

Windows devices commonly use the x64 architecture. On macOS, distinguish Apple Silicon from Intel by opening System Information and checking the chip or processor name under the hardware overview. On Linux, run uname -m in a terminal: x86_64 indicates x64, while aarch64 or arm64 indicates ARM64. Most recent Android devices use arm64, but choose the universal package if the architecture is unknown or installation reports incompatibility. Package downloads and architecture details are listed on the download page; do not install a package intended for another platform.

Separate the client, core, and node configuration

The graphical client, proxy core, and node configuration are three separate layers. v2rayN, v2rayNG, and v2flyNG handle the interface, subscriptions, startup controls, and system traffic capture. The Xray or V2Fly core parses protocols, creates outbound connections, applies routing, and handles DNS. A node configuration supplies the server address, port, user identifier, transport, and connection parameters such as TLS and REALITY. A successful client installation only means the interface can run; it does not mean a usable server configuration is available. Conversely, a node listed in a subscription does not guarantee that the selected core supports every parameter it uses.

For example, configurations containing REALITY or XTLS Vision parameters generally require an Xray core with the corresponding capabilities. Standard VMess, VLESS, and Trojan configurations must also match the address, port, transport, and security parameters exactly. When an import succeeds but the connection fails, do not immediately cycle through system proxy modes. First check which core the client is using, then compare it with the node requirements. For the functional differences between the two core families, see Xray vs. V2Fly Core: A Detailed Comparison.

Prepare subscription data and keep a fallback

Before the first setup, prepare a valid subscription URL, single-share link, QR code, or configuration file. Subscriptions are best for centrally managing multiple nodes; a single link is convenient for temporarily importing one configuration; a QR code works well for moving a small amount of configuration between a desktop and Android device; and file import suits complete, complex parameters. A subscription URL usually functions as an access credential and should not appear in public documents, screenshots, or shared logs. Preserve every character when copying, and watch for chat tools truncating the URL or adding spaces at either end.

Before changing the system proxy, TUN, DNS, or custom routes, keep a known-working baseline configuration. On desktop, export the current configuration or record the existing routing mode; on Android, duplicate the configuration before editing it. Change one variable at a time during troubleshooting: verify the node first, enable system capture next, then adjust routing and DNS. If the core, node, routing, and TUN are all changed at once, it becomes difficult to identify the failing layer.

Windows: Install v2rayN and manage the system proxy

Choose the desktop or classic WPF edition

The Windows download area offers the v2rayN desktop edition and the classic WPF edition. The desktop edition uses a newer cross-platform interface and suits fresh installations or users who want a similar workflow across desktop systems. The WPF edition is the long-standing classic Windows interface, suited to environments already familiar with its menus, tray controls, and configuration management. Both handle subscriptions, nodes, routing, and the system proxy, so they should not run simultaneously and compete for the same local port. Choose one edition for the first installation; decide whether to migrate only after verification.

After downloading, complete the installation as prompted. For an archive-based package, extract it to a fixed directory where the current user has write access. Do not run it from the archive preview window or place it in a temporary directory that is regularly cleaned. The program needs to save configuration, logs, and core files; a non-writable directory may let the interface open while causing subscription updates or core startup to fail. After the first launch, check the system tray. Closing the main window usually minimizes the program to the tray rather than exiting it. To stop it completely, choose Exit from the tray menu.

Import a subscription and select an active node

In subscription group management, add a subscription with a recognizable note and the complete URL, then choose Update current subscription or Update all subscriptions. Once the update finishes, nodes should appear in the main list. If nothing changes, first confirm that the group currently displayed is the one just updated, then check whether the log reports a failed network request, a parsing failure, or an empty response. Re-adding the same subscription creates duplicate groups and makes later updates easy to misdirect, so keep one clearly named group per source.

After choosing a node, set it as the active server. “Selected” in the node list and “started” for the core are separate states: the former chooses the configuration to use, while the latter makes the local proxy port listen. After starting the service, check the status bar and logs; a healthy setup should show that the local listener is established. Then use the client’s real connection test or open a browser page known to use the system proxy. Latency results are useful for comparison but cannot replace a real connection test. For the differences between the three latency metrics, see How to Read Latency Test Numbers.

How the system proxy works

The Windows system proxy mainly affects applications that read the system proxy settings. After choosing “Set system proxy automatically,” v2rayN points the system proxy to the local listening port and updates it with the client state. Browsers and many desktop programs read this setting, but some games, command-line tools, store apps, and software with its own network stack may ignore it. If the browser works but another program does not, first confirm that the program supports system proxy settings instead of immediately blaming the node.

The routing mode determines how requests entering the local proxy port are assigned to a proxied or direct outbound. A common “bypass LAN and mainland China” mode suits everyday rule-based routing: LAN addresses and requests matching direct rules avoid the remote node, while the rest follow the rules. Global mode is better for temporarily checking whether a domain was misclassified by a rule and should not become a long-term troubleshooting shortcut without understanding its scope. After changing routing, reconnect the current node so the core reloads the rules.

Administrator rights, port conflicts, and startup behavior

A standard system proxy usually does not require running continuously as administrator, but installing network components, enabling certain TUN implementations, or changing protected settings may require elevated privileges. Grant permission only when that operation calls for it. If the core exits immediately after startup, first look in the logs for “address already in use” or similar port-conflict messages. Common causes include another v2rayN instance, a different proxy client, or a leftover core process listening on the same port. Exit the duplicate program and restart the current client; do not hide the conflict by changing several ports at random.

Starting at login suits a dedicated device, but enable it only after the baseline configuration is stable. If both “launch client at startup” and “connect automatically after launch” are enabled, the proxy state changes soon after login. An expired subscription, unavailable network, or unusable previous node can then make the computer appear unable to access the network immediately after startup. A safer order is to launch the client, wait for the network to become available, and connect afterward, while keeping a tray-menu path to “clear system proxy.” If the program exits unexpectedly while the browser still tries to use the local port, disable the proxy in Windows settings and restart v2rayN.

Check whether the local port is listening:
netstat -ano | findstr LISTENING

View the program associated with a process ID:
tasklist /fi "PID eq process ID"

macOS: Install v2rayN, grant permissions, and configure the proxy

Choose the package for your chip

The macOS v2rayN packages are split between Apple Silicon and Intel. Open System Information and check the “Chip” or “Processor” field under the hardware overview: choose the ARM64 package for Apple silicon and the x64 package for Intel. A mismatched architecture may prevent the system from opening the app or may force it through a compatibility layer with additional issues. Get the correct file from the macOS download section before installing; do not infer the chip type from the device’s purchase year alone.

After opening the disk image, drag the app into the “Applications” folder and launch it from there. Running directly from the disk image complicates later saving, upgrades, and permission management. On first launch, the system checks the app’s source and displays a confirmation prompt; grant explicit permission through the app security page in System Settings. This only determines whether the system allows the app to start. If the interface opens but the core cannot run, check the client logs and core file status separately.

Import configuration and start the core

The subscription workflow is similar to Windows: add a note and URL, update the subscription, select a node in the target group, and start the service. The macOS clipboard may add line breaks when copying from a rich-text page, so check both ends of the URL after pasting. QR codes are useful for moving a single configuration from another device, while subscriptions remain preferable for batches of nodes and centralized updates. If an update succeeds but the node list is empty, check the group filter and subscription content type. If the log reports a parsing error, verify the format with the subscription provider instead of manually adding unknown parameters.

Once started, the core listens locally on an HTTP, SOCKS, or mixed proxy port. Check the active node, core status, and system proxy status separately in the client. A selected node does not mean system traffic is being captured, and an enabled system proxy does not prove that the core is listening. The most common broken state is a system proxy still pointing to a local port after the client has exited; browsers then keep trying to reach a service that no longer exists. Restart the client or disable the system proxy to restore basic connectivity.

System proxy behavior across applications

macOS stores the system proxy by network service, so Wi-Fi and Ethernet can have different settings. After v2rayN changes the proxy for the current service, browsers and apps that honor the system proxy send requests to the local port. Whether terminal tools use a proxy depends on the tool: some read environment variables, some read system network settings, and others require their own parameters. “The browser works but terminal requests go direct” is therefore not contradictory. If only browsers and standard apps need coverage, the system proxy is usually clearer; evaluate TUN when programs that ignore system proxy settings must also be covered.

After switching Wi-Fi, connecting Ethernet, or using a hotspot, recheck the proxy state for the current network service. If requests fail after waking from sleep while the client still appears to be running, disconnect and reconnect the current node to rebuild the underlying connection. Do not delete the subscription after every network change; the subscription stores configuration, while the network change only alters the path between the device and server. On corporate, authenticated, or captive-portal networks, disable traffic capture first, complete network authentication, and then start the proxy service.

TUN permissions, DNS, and clean shutdown

TUN creates a virtual network interface and changes routing, giving it broader coverage than a system proxy. The first activation may require system authorization. After authorization, check that the virtual interface exists, the default route changed as expected, and which layer handles DNS requests. If every request fails after enabling TUN, disable it and confirm that system proxy mode still works. This quickly separates a node or core problem from a virtual-network capture problem.

DNS problems often appear as unreachable domains even though direct connections to the target address or the client’s connection test still respond. Start with the client’s default routing and DNS combination, and avoid enabling multiple system-level DNS tools at once. If customization is necessary, determine which resolver handles direct domains and proxied domains separately so resolution does not conflict with the routing direction. Before exiting, disable the system proxy or TUN, then quit the client. If it terminates unexpectedly, inspect the active network service’s proxy settings and remove any configuration that still points to a local port.

Check the processor architecture:
uname -m

List the current network services:
networksetup -listallnetworkservices

Check the web proxy status for Wi-Fi:
networksetup -getwebproxy Wi-Fi

Linux: Install v2rayN, configure the desktop proxy, and use TUN

Confirm the distribution, architecture, and package format

The Linux download area provides v2rayN deb and rpm packages for x64 and ARM64. Debian, Ubuntu, and common derivatives generally use deb; Fedora, Rocky Linux, AlmaLinux, and other rpm-based distributions use rpm. Run uname -m to identify the architecture, then check /etc/os-release to confirm the distribution. The package format and processor architecture must both match; matching only one can still cause installer errors or prevent the binary from executing.

The graphical client depends on a desktop session, a notification area, and several runtime libraries. A server may install the package successfully without having the display environment required to show the v2rayN interface. This guide targets Linux devices with a desktop environment. Tray implementations can differ between Wayland and X11. If the tray icon is missing after closing the window, reopen the app from the application menu or check whether the desktop environment supports status icons. Do not launch multiple instances just because the tray icon is absent; duplicates can cause port conflicts.

Install with the system package manager

After entering the download directory in a terminal, let the package manager install the local file. Using the package manager instead of unpacking directly helps manage dependencies and later removal. The wildcard commands below assume the directory contains only one v2rayN package for the target architecture; if several files exist, enter the actual filename to avoid selecting an older package. If dependencies cannot be satisfied, refresh the distribution’s repositories and confirm that the system version is still supported, then retry.

Check the system and architecture:
cat /etc/os-release
uname -m

Install on Debian or Ubuntu:
cd ~/Downloads
sudo apt install ./v2rayN*.deb

Install on Fedora or an rpm-compatible distribution:
cd ~/Downloads
sudo dnf install ./v2rayN*.rpm

After installation, launch v2rayN from the desktop application menu. If starting it from a terminal reports a missing shared library, use the distribution’s package manager to install the dependency. Do not copy an individual library from an unknown source into a system directory. If the program starts but the core cannot execute, check the core file’s execute permission, whether the data directory is writable, and whether security policies block child processes. Before upgrading, exit the running client, then install the new package to avoid the old process retaining files or ports.

Import a subscription and configure the desktop system proxy

The order—add a subscription, update the group, select a node, and start the core—is the same as on other desktop systems. The main Linux difference is that desktop environments do not all use the same system proxy interface. GNOME, KDE, and other environments store proxy settings differently, so whether v2rayN can write to the current desktop proxy depends on environment support. After enabling it, check the desktop network settings to confirm that the proxy address points to the local machine and that the port matches the client status bar.

Many terminal programs do not automatically read the desktop proxy. To temporarily send tools in the current terminal session through a local HTTP proxy, set an environment variable using the port shown by the client. The variable applies only to the current shell and its child processes and disappears when the terminal closes. This is useful for testing, but do not add it to a global startup file before confirming that the port is stable.

Set a local proxy for the current terminal session:
export http_proxy=http://127.0.0.1:10809
export https_proxy=http://127.0.0.1:10809

Clear it after testing:
unset http_proxy
unset https_proxy

TUN, permissions, and network manager boundaries

TUN relies on a virtual network interface, routing tables, and the necessary permissions. Before enabling it, confirm that /dev/net/tun exists and avoid running other network tools that modify the default route at the same time. If the client reports insufficient permission, follow its local authorization flow; do not run the entire desktop session as root. The goal is to permit the required network operations, not to give every client file maximum privileges.

On Linux, DNS may be managed by systemd-resolved, NetworkManager, the desktop network manager, or another local service. If domain resolution fails after TUN starts, use ip route to check whether a route was created, then use resolvectl status to see which service currently owns DNS. If the command is unavailable, inspect the network manager used by the distribution. During troubleshooting, return to system proxy mode and verify the node first, then enable TUN separately. This keeps desktop proxy, core connection, and system routing issues from becoming tangled.

Android: Configure v2rayNG and v2flyNG

Choose a client and installation architecture

v2rayNG is the preferred Android client. It uses the Xray core and suits configurations involving common protocols such as VLESS, VMess, Trojan, and REALITY. v2flyNG uses the V2Fly core and is an alternative when that core behavior is required. Both clients can be installed on the same device, but only one app can establish the VPN service at a time. Disconnect the current client before switching to avoid the status bar showing an old service while the new client cannot obtain capture permission.

Most recent devices can use an arm64 package. If the architecture is unknown or the arm64 package is reported as incompatible, use the universal version. On first launch, allow the required network connection permission. Notification permission affects how easily connection status can be monitored, but it does not determine whether node parameters are correct. When Android asks to establish a VPN connection, the confirmation dialog is the standard step through which Android hands app traffic to the client via the local VPN interface.

Import with subscriptions, the clipboard, and QR codes

To import a subscription, add its name and complete URL in the subscription group, then update it. Some systems restrict background clipboard access, so if clipboard import fails, paste the URL manually on the add screen. QR codes are suitable for importing a single shared configuration. Before scanning, confirm that the code comes from a trusted source, then check that the imported protocol, address, port, and transport parameters are complete. A blurry or cropped code may not scan, but that does not prevent importing through the subscription URL.

After a successful subscription update, choose a configuration from the node list and return to the main screen. With multiple groups, confirm that the selected node belongs to the group just updated. A node remark is only for identification; the connection depends on the address, port, user identifier, protocol, transport, security layer, and server name. When editing manually, do not compare only the first few fields. WebSocket paths, gRPC service names, TLS server names, REALITY public keys, and short IDs are especially important: any missing value can cause a handshake failure.

VPN service, per-app proxying, and background limits

After you tap Connect, v2rayNG or v2flyNG starts a local VPN service. Unlike a desktop system proxy, app traffic enters a virtual system network interface and the client uses routing rules to choose direct or proxied access. A VPN icon in the status bar only confirms that the interface exists; it does not prove that the remote node works. Check the client log or open the target service after connecting. If it disconnects immediately, focus on configuration parsing and core startup logs.

Per-app proxying controls which applications enter the client. Allowlist mode handles only selected apps, while blocklist mode handles apps that have not been excluded. A common symptom of misconfiguration is that the browser works but the target app bypasses the proxy, or that a system component is unintentionally included and behaves incorrectly. For the first connection, avoid complex per-app rules. Confirm the basic connection first, then add apps one at a time. Reconnect after changing the app list so the VPN routes are rebuilt.

Android power-saving policies can restrict background processes. If the connection drops after the screen has been off for a while and returns only when the app is reopened, allow the client to run in the background in the system battery settings and remove it from aggressive sleep lists. Setting names vary by manufacturer; the key question is whether the client process is terminated after the screen locks. A persistent notification helps the system and user identify connection status. Do not force-stop the app to disconnect; tap Disconnect in the client so the VPN interface and routes are released cleanly.

Per-app rules, LAN access, and DNS

To access devices on the local network, ensure private address ranges use a direct route. Home routers, printers, and storage devices commonly use 192.168.0.0/16, 10.0.0.0/8, or 172.16.0.0/12. If global proxy mode prevents access to these devices, switch to a routing mode with LAN direct rules instead of adding a remote rule for every device. Switching between mobile data and Wi-Fi changes the underlying connection, so the client may need to reconnect. This is a rebuilt network path, not a reason to re-import the subscription.

Android Private DNS, the client’s DNS settings, and node-domain resolution can affect one another. If an address works but the domain form fails, first restore the client’s default DNS and temporarily disable extra system-level DNS settings for comparison. If only certain domains take the wrong path, check whether the routing rules match domain names or resolved addresses. Do not change Private DNS, client DNS, routing mode, and node security parameters at the same time, or the comparison becomes meaningless.

Manage subscriptions, nodes, and cross-device configurations

A subscription update is not a client upgrade

Subscription updates, client upgrades, and core updates are three separate operations. A subscription update rereads the node list from an existing URL and may add, remove, or change nodes. A client upgrade updates the graphical interface and management logic. A core update affects protocol implementation and connection behavior. When troubleshooting, record exactly which layer changed. If one node fails after a subscription update, compare its parameters or try another node from the same subscription. If several previously working configurations fail after a core update, inspect the core logs and configuration compatibility.

Group subscriptions by source and use clear remarks. Do not merge multiple sources into an untraceable list or accumulate duplicates under vague names such as “Default” or “Test.” Confirm the target group before updating, then check that the node count and remarks match expectations. Some subscription updates remove nodes deleted by the provider, so manual edits to subscribed nodes may be overwritten during the next update. For personalized configurations that must persist, copy them into a separate local configuration and edit the copy.

When to use each import method

Subscription URLs suit multiple nodes and ongoing maintenance; share links are convenient for quickly transferring one node; QR codes work well for moving a small amount of configuration between nearby devices; and configuration files can carry a fuller inbound, outbound, routing, and DNS structure. A share link usually describes one outbound node and may not include client-level routing policies. After copying from desktop to Android, node parameters may remain intact, but system proxy, per-app proxy, and TUN settings do not migrate automatically.

When importing a configuration file, distinguish a “client backup” from a “core configuration.” A client backup may include groups, interface settings, and local paths and is intended for the same client ecosystem. Core JSON describes lower-level inbound, outbound, and routing structures, and a graphical client may not accept every custom field. When import fails, identify the file type first instead of treating arbitrary JSON as a node file. For three common ways to sync configurations across devices and their trade-offs, see Three Ways to Sync V2Ray Configurations Across Devices.

Understand node parameter dependencies

Protocol fields cannot be evaluated in isolation. VLESS and VMess both require a server address, port, and user identifier; Trojan authenticates with password-based credentials. The transport may be TCP, WebSocket, or gRPC, while the security layer may use TLS or REALITY. With TLS, the server name usually participates in certificate verification. With WebSocket, the path and request host must match the server. With gRPC, the service name must match. REALITY also depends on parameters such as the public key, server name, and short ID. Changing only the protocol name while keeping incompatible transport parameters will not produce a working configuration.

Node remarks, group names, and latency sorting are client management data and do not participate in the protocol handshake. An address may be a domain or network address; a domain must be resolved first, so DNS problems occur before the server connection begins. If the log shows domain resolution failure, fix DNS first. If it shows connection refused or timed out, check the address, port, and network path. If failure occurs during TLS or REALITY negotiation, focus on the security parameters. Reading logs by connection stage is more effective than vaguely “trying another mode.”

Secure storage and update cadence

Subscription and share links may contain all the information required for access. Store them in a controlled password manager or secure device storage, not in public notes, forum posts, screen recordings, or unredacted logs. When sharing troubleshooting details, keep the protocol, transport, and error stage, but remove the server address, user identifier, password, public-key settings, and subscription URL. Client logs may record destination addresses, so read them before sharing.

Set the update cadence to match actual use. Refreshing a subscription constantly does not improve connection quality and may overwrite the current list when the provider is temporarily unavailable. Use the client’s scheduled update feature, or update manually when a node fails or configuration changes are announced. After updating, keep the existing selection until the new list has been verified. Devices using the same subscription do not need to refresh simultaneously, but avoid leaving one device indefinitely on parameters that have already been removed.

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

System proxy, TUN, routing, and DNS

The fundamental difference between system proxy and TUN

A system proxy publishes a local proxy address through the operating system. Only apps that actively read this setting hand requests to the client. It is simple to configure and has a clear scope, making it suitable for browsers and standard desktop applications. TUN uses a virtual network interface to receive a broader range of traffic, then lets the core choose direct or proxied access. It can cover programs that do not support system proxies, but it also involves routing tables, DNS, permissions, and a virtual interface, creating more layers to troubleshoot.

Choose the mode based on application needs. If only browsers, office software, and tools that clearly support proxies need coverage, start with the system proxy. Enable TUN when a program ignores the system proxy or broader traffic coverage is required. Android clients capture traffic through the system VPN service, which resembles desktop TUN in use but leaves permissions and routing to the mobile operating system. Do not let multiple clients modify the system proxy or create virtual interfaces at the same time, or traffic may loop, be misrouted, or leave through an unpredictable path.

How routing rules match traffic

Routing rules typically match requests by domain, network address, port, protocol, or inbound tag, then send them to a proxy, direct, or blocking outbound. When rules are ordered, a request that matches an earlier rule does not continue into later generic rules. Write custom rules from specific conditions to broad ones, leaving the default outbound last. LAN and private addresses should generally be routed directly first, preventing requests to routers, printers, and local services from going through a remote node.

Domain matching and network-address matching occur at different stages. With domain:, full:, or rule-set matching, the core can choose a route from the domain in the request. If an app connects directly to an address, domain rules do not apply. Some policies resolve the domain first and then match the resulting address. Changing domainStrategy affects this process; understand the current rule source before changing it, and do not treat it as a universal speed toggle.

DNS and routing must work together

DNS converts domain names into connectable addresses, while routing decides which outbound handles the DNS request and the subsequent connection. When they disagree, a domain may resolve to an address unsuitable for the current outbound, or the DNS request itself may be blocked along the wrong path. Common symptoms include a responsive node connection test with inaccessible web domains, repeated timeouts for certain domains, a change after switching to a network address, or every domain failing after TUN is enabled.

When troubleshooting DNS, restore the client’s default setup first and confirm that the node and basic routing work. Then check for other DNS tools, browser Secure DNS, or enterprise network policies at the operating-system level. Keep one primary control layer. If customization is necessary, direct domains can use a locally reachable resolver while proxied domains follow the client’s DNS plan, but the exact rules must match the selected core’s capabilities. Do not copy large DNS configurations from unknown sources; their listen addresses, outbound tags, and routing tags may not match this device at all.

Verify where traffic is actually going

Do not verify routing from the client icon alone. First check the core log for the target domain or address and the selected outbound tag. Compare that with the active routing rules and confirm that the matched condition is expected. If the log contains no target request, the application has not entered the client; check the system proxy, environment variables, per-app proxy, or TUN capture layer. If the request appears but uses the wrong outbound, fix rule order. If the direction is correct but the connection fails, inspect the node and network path.

Temporarily switching to global mode is a comparison test. If the same node works globally but not under rule-based routing, the problem is usually routing or DNS. If neither mode works, check the node, core, and basic network first. Restore the original mode after testing and reconnect the current node. Using global mode as a permanent fix hides rule errors and may reroute LAN and ordinary direct traffic unnecessarily.

Configuration maintenance and troubleshooting

Follow a layered troubleshooting sequence

Troubleshoot layer by layer: basic network, client process, core startup, node connection, traffic capture, routing and DNS, then the target application. First confirm that the device can access the current network and complete any captive-portal login. Next verify that the client has not been terminated and that the core is listening locally. Then test the node connection. Finally inspect the system proxy, TUN, per-app rules, and target-app behavior. Move to the next layer only after the current one passes. This avoids repeatedly changing DNS when the node is down or switching nodes when the application never entered the proxy.

Logs are the primary evidence. Configuration parsing errors during startup usually point to a field or format problem. Listener failures commonly indicate a port conflict or insufficient permission. DNS errors occur before connecting to the destination. Connection timeouts may come from the address, port, route, or remote status. Handshake errors involving TLS, REALITY, WebSocket, or gRPC require checking the corresponding security and transport parameters. Recording the stage where the error occurs is more useful than capturing only the final line.

Subscription update fails or no nodes appear

When a subscription update fails, first check that the URL is complete and contains no spaces or line breaks, then review the update log for the response status and parsing result. If the current network cannot reach the subscription address, verify the basic network and DNS first. If content is retrieved but parsing fails, its format does not match the client’s expectations. Do not use an ordinary web page URL as a subscription URL, and do not manually edit encoded content you do not understand.

If the log reports a successful update but no nodes appear, check the current group filter, search box, and selected subscription group. An old search term can hide every new node. If nodes appear and quickly disappear, a later update may have returned a new list that removed the old entries. Copy configurations that must be kept into a local group so subscription synchronization cannot overwrite them. When devices behave differently, compare their last update times and client cores instead of comparing node remarks alone.

Connection succeeds but the app cannot access the network

A client showing Connected does not guarantee that the target app entered the proxy. In desktop system-proxy mode, start with a browser that honors the system proxy. For command-line tools, check environment variables or the tool’s own proxy parameters. On Android, check the per-app proxy list. In TUN mode, inspect the virtual interface and routes. If the log contains no requests from the target app, the issue is in the capture layer. If requests appear and use the proxy outbound, continue with domain resolution, the node route, and the app protocol.

When only some sites fail, use global mode temporarily for comparison. If global mode works, inspect rule matching and DNS. If it still fails, test another node from the same subscription to separate the node from local configuration. For slow speeds, investigate the node, the intermediate route, and local settings as separate layers; do not enable several “optimization” options at once. For the full layered method, see A Layered Approach to Troubleshooting Slow V2Ray Speeds.

Startup failures, port conflicts, and leftover proxies

If the core stops immediately after starting, first check whether the local port is occupied. Exit other proxy clients and duplicate v2rayN instances, then confirm that no old core process remains. If you change the port, update the port referenced by the system proxy or environment variables as well; changing only one side leaves the system connecting to the old address. For permission errors, check whether the program directory is writable, the core file is executable, and TUN operations have the required authorization. Do not store the configuration directory on read-only media or in a temporary location that automatically rolls back.

After an unexpected client exit, the system proxy may still point to the local listening port. A typical symptom is that every application honoring the system proxy fails while disabling the proxy immediately restores access. Clear the proxy in the operating system’s network settings, or reopen the client and choose “Clear system proxy.” For leftover TUN state, confirm that the virtual interface and routes have been released; if necessary, start the client normally before disconnecting. Restarting the device may clear some temporary state, but afterward continue investigating the log cause of the unexpected exit.

A maintenance cadence for clients, cores, and configurations

Do not perform all three types of update at once. Record the currently working node, routing mode, and capture method, then update the client alone and verify that it starts. Update the core only if needed and verify existing nodes, then update the subscription last. If a problem appears after one step, you know where to look. Exit the desktop client normally before upgrading; disconnect the VPN service before updating on Android. If multiple desktop versions are kept for rollback, place them in separate directories and run only one instance at a time.

Periodically remove obsolete local copies, duplicate subscriptions, and custom rules that are no longer used. The more rules there are, the harder priority conflicts become to understand. A stable configuration should remain explainable: know where each subscription came from, why the current core was selected, why the system proxy or TUN is enabled, and which rules handle direct access. For first-run setup, also see the v2rayN First-Run Setup Guide. If you only need to repeat the shortest workflow, return to the Quick Start Guide.