Complete V2Ray Installation and Configuration Guide

01 / PREPARATION

General Preparation: Understand Clients, Cores, Subscriptions, and Nodes

Four Components, Four Different Roles

Before installing anything, distinguish the interface, proxy core, subscription, and node. v2rayN, v2rayNG, and v2flyNG are clients that manage settings and provide the control interface; Xray and V2Fly cores handle protocol parsing, transport connections, route matching, and local listeners. A subscription is an updateable collection of server configurations, while a node is one outbound configuration in that collection. Installing a client does not create a subscription, and importing one does not mean a usable node has been selected. A complete connection requires a client, a startable core configuration, a current node, and the correct local proxy entry point.

Use v2rayN as the standard choice on desktop platforms. On Windows, choose between the desktop edition and the classic WPF edition; on macOS and Linux, use the v2rayN package for the matching architecture. On Android, v2rayNG with the Xray core is the default choice; use v2flyNG when the V2Fly core is required. Installation entry points for all three clients are collected on the package downloads page. This guide does not distribute files or hard-code version numbers.

Check Your System and CPU Architecture Before Downloading

Most Windows devices should use x64. On macOS, check the processor first: choose arm64 when System Information shows Apple silicon and x64 when it shows Intel. On Linux, identify both the architecture and package format: Debian, Ubuntu, and derivatives generally use deb, while Fedora, Rocky Linux, and openSUSE generally use rpm. Most recent Android devices use arm64; switch to the universal package only when the architecture is unknown or installation reports incompatibility.

Check the Source and Fields Before Saving a Subscription

Subscription URLs are generated by service providers and usually contain access credentials, so store them as sensitive configuration. Do not paste them into public logs, screenshots, or online parsers. Before importing, make sure chat software has not truncated the URL, that there are no leading or trailing spaces, and that copying from a browser has not added line breaks. If the provider offers a regular subscription, a client-specific subscription, and single-node links, choose the format explicitly marked as compatible with your client. Use a single-node link to test the client itself only when subscription updates keep failing.

A node configuration usually includes a server address, port, protocol identity fields, and transport parameters. With TLS or REALITY enabled, it may also include a server name, fingerprint, public key, short ID, or path. When editing manually, keep these fields consistent as a group; do not replace only the address and port. VMess, VLESS, and Trojan describe authentication and session methods, while WebSocket, gRPC, and TCP describe the transport. These two categories are not interchangeable.

Build the Smallest Testable Connection First

For a first setup, do not enable TUN, custom DNS, complex routing, and multiple subscriptions at once. A safer sequence is: install the client, import one subscription, update the server list, select one node, start the core, and enable the system proxy to test browser access. Once this minimal path works, add groups, automatic updates, TUN, and custom rules one at a time. If something breaks, you can then identify which step introduced the variable.

Keep the client log window open during testing. A normal startup should show a local SOCKS or HTTP listener, with no port conflict, configuration parsing error, or permission denial. A successful request only confirms that the complete path works; it does not prove that every layer is configured correctly. If the client says it is connected but pages do not open, verify that the system proxy points to the client’s actual listening port instead of repeatedly switching nodes. For more detailed fault isolation, see the checklist for a connected proxy with no web access.

02 / WINDOWS

Windows: Install v2rayN, Import Subscriptions, and Configure System Takeover

Choose the Desktop or Classic WPF Edition

The Windows downloads provide the v2rayN desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface and suits users who want a layout similar to macOS and Linux; the WPF edition follows traditional Windows conventions, with menus closer to older tutorials. Both manage subscriptions, nodes, cores, and routing, so there is no need to install both. Before switching editions, export custom servers and rules and exit the old client to prevent two instances from competing for the same local port.

After installation, launch v2rayN from the Start menu. If Windows asks for network access on first run, allow only the network type you actually use. On corporate or public networks, do not grant extra network access without review. The client’s local listener should normally remain on the loopback address; it does not need to listen on the LAN. For portable use, avoid placing the program in a system temporary directory or one continuously locked by sync software. Configuration and log files need reliable write access.

Import a Subscription and Select the Active Server

Open subscription group management, add a group, and enter the subscription URL. Name the group after its source or purpose rather than using an indistinct label such as “Group 1.” Save it and update the subscription. Nodes appearing in the main list indicate that parsing has completed. Filter by name, region, or protocol, select a server, and set it as active. Clicking a row to highlight it does not always switch the current outbound; check the status area for the active server name.

Updating a subscription rereads the remote server list. Keep manually added nodes in a separate group so updates cannot overwrite them. When several subscriptions are configured, each group can have its own update interval, but avoid intervals that are too short. Updating once at startup and manually when needed usually makes changes easier to trace. For large node lists, see practical subscription grouping and server filtering for organizing notes, keywords, and sorting.

Start Verification with the System Proxy

The system proxy is a good first test for browsers and apps that follow Windows proxy settings. Start the core, choose the system proxy option from the tray menu, and visit a target site. This usually points the system HTTP and HTTPS proxies to v2rayN’s local listener, while the core decides whether traffic goes direct, through the proxy, or is blocked according to the active routing rules. If the browser works but one program does not, that program probably ignores the system proxy; it does not necessarily mean the node has failed.

When you need to check ports, inspect listening sockets from a terminal. Use the ports shown in the client settings; do not assume every installation uses the same values.

netstat -ano | findstr LISTENING
Get-NetTCPConnection -State Listen | Sort-Object LocalPort

If the log says a port is already in use, first verify that the SOCKS, HTTP, and API ports are not duplicated in the settings, then identify the process using the port. Do not terminate an unrecognized system process. Safer options are to exit an older client, disable duplicate startup items, or move v2rayN’s local ports to unused values before restarting the core.

TUN Mode and Windows-Specific Issues

TUN uses a virtual network interface to capture more traffic that does not read system proxy settings. Before enabling it, exit other network tools of the same type and confirm that v2rayN has permission to create the virtual interface. Windows may briefly re-detect the network during the first activation; a short interruption is part of the interface switch. If connectivity does not return, disable TUN immediately, verify that system proxy mode still works, and then inspect the virtual interface, DNS, and routing rules instead of reinstalling everything at once.

Common Windows-specific issues include security software temporarily blocking a core subprocess, a virtual interface becoming unsynchronized after sleep, system proxy settings remaining after an abnormal exit, and enterprise policies overriding proxy settings. Before exiting normally, disable the system proxy or TUN. If the client has quit but the browser still tries to use the local proxy, turn off the manual proxy in Windows proxy settings and restart the client. After sleep, restart the core first; if that fails, disable and re-enable TUN. Deleting the entire configuration is usually unnecessary.

03 / MACOS

macOS: Install v2rayN for Your Chip and Handle Permissions and Proxy Residue

Identify the Chip and Install the Matching Package

Open System Information or “About This Mac” and check the processor type. Choose the arm64 package for Apple silicon and the x64 package for Intel. The wrong architecture commonly causes the app to fail to launch, quit immediately, or rely on a compatibility layer. Return to the macOS download page and choose the matching package rather than trying to hide an architecture problem by repeatedly changing permissions.

Place v2rayN in the Applications folder during installation and launch it from there. When macOS requests permission for network access, notifications, or background items, grant only what the client actually needs. If the system cannot verify the app’s source, first confirm that the file came from this site’s download page, then review the blocked app in Privacy & Security and allow it there. Do not install supposed dependencies from unknown reposting sites.

Import Subscriptions and Manage the Configuration Directory

Open subscription settings, add a group, paste the complete subscription URL, save it, and update. If the update succeeds but the list is empty, check whether keyword filtering is enabled or only one group is visible, then review the subscription parsing result in the logs. If the URL returns content in a browser but keeps failing in the client, check the system clock, proxy loops, and certificate server name before assuming the subscription is invalid.

Keep manual and subscription nodes in separate groups. Before changing package architecture or reinstalling, use the client’s export function to save custom nodes and routing rules. The configuration directory is not suitable as a shared folder: sync tools can create conflict copies while the client is writing, leaving duplicate or truncated JSON. If settings suddenly revert after startup, exit the client and check whether multiple configuration copies are being synchronized.

What the System Proxy Covers

When the system proxy is enabled, v2rayN changes the Web proxy settings for the current network service. Browsers and apps that follow system networking connect to the local HTTP or SOCKS entry point, while apps with their own network stack may ignore those settings. After switching between Wi-Fi, USB, and Ethernet, confirm that the new network service also has the proxy applied, because macOS stores some settings separately for each service.

Use system commands to list the current network services, then inspect the proxy status. Service names may be localized, so use the output of the first command as the authoritative reference.

networksetup -listallnetworkservices
scutil --proxy

If the client has exited and pages no longer open, turn off the current network service’s Web Proxy and Secure Web Proxy in Network settings, then restart v2rayN. Do not manually change the system proxy port to a different value while the client is running; the interface and actual system settings will diverge. To customize ports, change them in the client and restart the core so the system proxy is updated accordingly.

TUN, DNS, and Wake-from-Sleep Recovery

macOS TUN mode creates a virtual network interface and changes routing, so the first activation may require system authorization. After granting it, test with the default route and DNS settings before adding custom domain rules. If networking does not recover after TUN is disabled, check in order whether the virtual interface disappeared, the default route returned to the physical network, and system DNS is still pointing to a stopped local port.

Sleep with the lid closed, network changes, and hotspot changes can alter interface order. If the client appears to be running but cannot access anything after wake, restarting the core is more useful than refreshing the subscription; it rebinds the listener, routes, and DNS to the current network. Re-enable TUN only after system proxy mode works and a single-node test succeeds. For persistent TLS errors, also verify automatic time synchronization and that the server name matches the node configuration. See TLS handshake and certificate error troubleshooting for the relevant checks.

The macOS firewall or endpoint-management policies may restrict background network extensions. If logs clearly show permission denial, follow the device-management policy instead of repeatedly reinstalling. On managed devices, proxy policies may be overwritten at login, so the client settings can be correct while the system proxy fails to persist. Compare the system proxy query with the client’s listening status to determine whether the issue is in the policy layer or the core.

04 / LINUX

Linux: Package Installation, Desktop Proxy, Environment Variables, and TUN

Choose a Package by Distribution and Architecture

The Linux version of v2rayN provides deb and rpm packages for both x64 and arm64. First run an architecture check: choose x64 for x86_64, and arm64 for aarch64 or arm64. Debian, Ubuntu, and derivatives generally use deb; Fedora, Rocky Linux, and distributions using RPM package management use rpm. Do not force installation on other distributions by unpacking the package, as desktop entries, dependencies, and uninstall records may not be maintained correctly.

uname -m
cat /etc/os-release

After downloading, run the appropriate installation command from the directory containing the file. Replace the filename in the command with the exact filename shown on the downloads page.

sudo apt install ./v2rayN-package.deb
sudo dnf install ./v2rayN-package.rpm

apt install ./file.deb resolves dependencies available from configured repositories and is more suitable for ordinary installation than calling a low-level unpacking command directly. On rpm-based distributions, dnf install likewise preserves dependency resolution. If dependencies cannot be satisfied, refresh the distribution’s repositories and inspect the missing library names; do not mix base libraries from different distributions. After installation, launch from the desktop application menu. When launching from a terminal, keep the output visible to capture graphics or permission errors.

Subscription Import and Desktop Sessions

v2rayN subscription handling is consistent across desktop platforms: create a group, enter the subscription URL, update servers, select an active node, and start the core. On Linux, also pay attention to the graphical session. Launching the graphical client as an administrator can change ownership of the configuration directory, preventing a regular user from writing to it later. Use elevated commands only for package installation and TUN permission setup; do not run v2rayN as an administrator long-term.

Desktop environments expose system proxy settings in different places. GNOME, KDE, and others usually provide network proxy settings, but whether each app reads them depends on its networking implementation. After enabling v2rayN’s system proxy, test the browser and terminal programs separately. If the browser works but command-line tools connect directly, the terminal is not reading the desktop proxy; the core is not necessarily at fault.

Proxy Environment Variables for Terminal Programs

When only the current terminal session needs to use the local HTTP proxy, set environment variables temporarily. The port must match v2rayN’s HTTP inbound. Run unset when finished so package managers and internal tools do not continue using the local proxy unexpectedly.

export http_proxy=http://127.0.0.1:local-http-port
export https_proxy=http://127.0.0.1:local-http-port
export no_proxy=localhost,127.0.0.1
unset http_proxy https_proxy no_proxy

“local-http-port” is explanatory text and must be replaced with the number shown in the client settings before execution. Do not permanently add these variables to global configuration for all users unless you have assessed their effect on login, updates, containers, and background tasks. A SOCKS proxy cannot be used directly as an HTTP proxy by every program; when a program explicitly supports SOCKS, enter socks5://127.0.0.1:port in its expected format.

TUN Permissions, Routing, and DNS

Linux TUN depends on a virtual network device, routing support, and the required permissions. If activation fails, first confirm that the device exists, then use the logs to determine whether the cause is insufficient permission, an unavailable module, or a failed route addition. Do not grant the entire client unrestricted administrator access. If the distribution uses capabilities or a service component to authorize TUN, follow the client’s installation procedure and check after updates that the permission remains valid.

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

If domains cannot be resolved after TUN is enabled but a known address still responds, the problem is usually in the DNS path. If both fail, check the default route, policy routing, and firewall first. On systems using systemd-resolved, verify the DNS actually used by the current interface rather than relying only on the surface contents of /etc/resolv.conf. NetworkManager may rewrite DNS and routes after reconnecting, so restart the core and recheck them after a network change.

Another Linux-specific issue is separation between the desktop session and background processes. Closing the window may leave the client in the tray or terminate it with the desktop session. Before ending a remote session, stop the system proxy or TUN so environment variables do not remain after the local listener disappears. When logs show “address already in use,” use ss -lntup to find the listening process, then check for a duplicate v2rayN launch or an old core instance.

05 / ANDROID

Android: Install v2rayNG or v2flyNG and Route App Traffic

Choose a Client and Package Architecture

v2rayNG is the preferred Android client. It uses the Xray core and supports common protocol and transport configurations. Choose v2flyNG when the V2Fly core is required. Both can be installed separately, but only one client should normally establish the system VPN interface at a time; the app started later may replace the earlier connection. Packages are available in arm64 and universal versions. Prefer arm64 on recent mainstream devices and use the universal version when installation is incompatible or the architecture is unknown.

Get the package from the Android download page. Android may ask you to allow the current browser or file manager to install apps. After installation, disable that temporary install permission for the source. During an upgrade, install the package for the same client over the existing app to preserve its configuration. If the system reports a signature mismatch, do not uninstall and reinstall blindly; verify the download source and app name, exporting the configuration first if necessary.

Import a Subscription and Select a Node

Open v2rayNG, go to subscription group settings, add and save the subscription URL, then run Update subscription from the menu. Return to the main list when the update finishes and tap a node to make it the active configuration. The check mark in the list or status area confirms the current node. If the update reports success but no new nodes appear, check the selected group, whether the subscription returned empty content, and whether list filters are hiding the new entries.

You can also import a single link from the clipboard to test a node or isolate a subscription parsing issue. The clipboard may contain chat text alongside the link, so copy only the complete configuration link before importing. A QR code is useful for moving one configuration from another device, but it contains access parameters and should not be displayed publicly. Maintain large node sets through subscription groups rather than updating server parameters one by one.

Start the Connection and Route Apps

Tap the connect button after choosing a node. The first time Android creates a VPN interface, it displays an authorization dialog. After confirmation, the client creates a local traffic entry point and uses routing settings to decide which connections go through the proxy outbound. A connection indicator only shows that the interface exists; it does not prove that the remote handshake succeeded. Check the client’s test results and logs as well. If a node test fails, try another node in the same subscription first to determine whether the issue affects one node or every configuration.

Android per-app proxying lets you choose which apps enter the client, helping avoid unnecessary local traffic. Clearly choose between “proxy only selected apps” and “bypass selected apps”; the two modes are opposites. Reconnect after changing the list so the system interface loads the new rules. If the browser works but a target app does not, first inspect the per-app list, the app’s own DNS behavior, and background network restrictions.

Background Restrictions, Private DNS, and Network Switching

Battery-saving policies may restrict v2rayNG or v2flyNG in the background, causing the connection to drop after the screen has been locked and recover only when the app is reopened. In battery settings, allow the client the background activity it needs and ensure Data Saver is not blocking it. There is no need to grant permissions unrelated to networking. If a task killer force-stops VPN apps, exclude the current client from its automatic termination list.

With Android Private DNS enabled, domain requests may bypass the DNS path expected by the client or resolve differently from the node configuration. If a domain is unreachable while its address works, temporarily switch to automatic DNS for comparison, then decide whether the system setting or the client should handle DNS. Do not enable several custom DNS layers at once; otherwise logs show only the final failure and make it difficult to identify where the request was rewritten.

Switching between Wi-Fi and mobile data changes the local egress path. The connection may still look active even though the underlying session is invalid, so disconnect and reconnect. On a public network requiring captive-portal login, pause the client, complete network authentication, and resume the connection. If only one network fails, compare its DNS, IPv6, and port restrictions instead of deleting the subscription. For TLS errors, also verify automatic time synchronization and that the node’s server name is complete.

06 / SUBSCRIPTION · ROUTING

Subscriptions, Nodes, and Split Routing: A Cross-Platform Management Method

Updating a Subscription Does Not Switch Nodes

A subscription update retrieves the node collection from a specified URL, while switching nodes changes the active outbound. They are separate operations. An update may remove, rename, or modify an old node, so if the client still shows its previous name, return to the server list and verify the selected item. For automatic updates, use a sensible interval and inspect one manual update first. Frequent requests do not make nodes more reliable; they make configuration changes harder to trace.

In multi-subscription setups, create groups by source and use notes for region, route, or purpose. Do not infer protocol or security parameters from a node’s original name; it is display text only. Open the details to inspect the protocol, address, port, transport, security layer, and server name. When the provider maintains the subscription nodes, avoid editing core fields individually unless you know exactly why; the next update may overwrite local changes.

Create a Reversible Configuration Baseline

Before adding complex rules, preserve a working baseline: one subscription, one verified node, default routing, and default DNS. Change one category at a time—for example, add domain direct rules first, test them, and then add address rules. This gives you a known-good state to return to. If the client supports exporting, export the configuration before major changes to groups and routes. Exported files contain node access parameters and must be stored as sensitive files.

Node tests are filtering tools, not proof of end-to-end connectivity. A successful TCP connection shows that the server port accepts a connection; it does not prove authentication, TLS, transport, or the final outbound path. For a real assessment, combine the result with core logs and one complete request. If every test suddenly fails, check the local network, system time, DNS, and subscription fields before deleting all nodes.

Understand Route Matching Order

Routing rules are usually evaluated in order; the first match determines whether traffic goes direct, through the proxy, or is blocked. Broad rules placed first can override later specific rules. For example, a proxy rule covering every domain leaves no chance for a later direct rule for one domain to run. A maintainable order is: explicit LAN and local targets, specific domains needing special handling, category rules, and the default outbound last.

The following is a simplified example of a core routing structure, showing field hierarchy and matching behavior. Actual outbound tags must match the configuration generated by the client; do not assume their names.

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

geoip:private matches common private address ranges so LAN devices are not sent to a remote endpoint. The example domains only illustrate rule syntax. A client’s graphical interface may wrap these fields as preset rules, but verify the preset’s matching order and default outbound before enabling it. Address and domain rules are not completely equivalent: when an app resolves a domain locally before connecting to an address, what the core can see depends on the takeover mode and DNS flow.

Check Observable Information When Routing Fails

In system proxy mode, apps that support HTTP proxying usually pass the domain to the proxy entry point, making domain rules easier to apply. Some apps resolve locally before connecting to an address and may therefore match only IP rules. TUN can capture more traffic, but it also requires DNS sniffing and routing configuration. When split-routing results are unexpected, first confirm in the logs which rule actually matched, then adjust the order instead of inferring the egress from the site’s displayed content.

To keep a LAN printer, router administration page, or development service on a direct connection, retain direct rules for private addresses and check that the client permits local-network access. If the system proxy binds only to the loopback address, local apps can use it but other LAN devices cannot. Do not enable LAN listening unless sharing is explicitly required. Shared listening also involves firewall rules, access controls, and network boundaries, beyond ordinary single-device setup.

07 / PROXY · TUN · DNS

System Proxy, TUN, and DNS: How the Three Paths Work Together

The System Proxy Handles Only Apps That Use a Proxy

A system proxy points the operating system’s HTTP, HTTPS, or SOCKS settings to the client’s local listening port. Browsers and programs that follow system settings connect to that port, and the client forwards requests through the active node. Its advantages are a clear path, low permission requirements, and easy recovery. Its limitations are that some programs ignore system proxy settings, while UDP traffic and custom network stacks may bypass the entry point.

When troubleshooting the system proxy, verify three values together: the proxy address in system settings, the proxy port, and the address the client is actually listening on. Common mistakes include changing the client’s local port while the system retains the old value, or leaving the system pointed at a nonexistent local port after the client exits. Disable the system proxy before normal shutdown to reduce residue. If the system proxy works but one app does not, inspect that app’s own proxy settings instead of switching immediately to global routing.

TUN Takes Over the Network Interface and Routes

TUN creates a virtual network interface and uses system routes to send more traffic through the client. It suits apps that do not support system proxies, desktop environments requiring consistent split routing, and some UDP scenarios. Because it operates lower in the stack, interface permissions, default routes, DNS, firewalls, and other virtual network tools can all affect the result. First verify that the same node works in system proxy mode; otherwise you will be troubleshooting the remote node and local interface at the same time.

After TUN is enabled, the system usually has a physical interface, a loopback interface, and a virtual interface. The default or policy route determines which path traffic takes. If the entire network goes down immediately, disable TUN to restore basic connectivity, then inspect interface creation and route-addition results in the logs. Do not change several DNS and MTU settings while offline, because after recovery you will not know which change helped.

DNS Determines How Domains Enter Routing Decisions

DNS does more than translate a domain into an address; it also affects whether domain rules can be matched accurately. In system proxy mode, an app may send the domain to the local proxy or resolve it first. In TUN mode, the client can take over DNS and preserve the relationship between the domain and connection. If DNS requests bypass the client, the routing layer may see only the destination address, so domain-based rules may not work as intended.

Common DNS failures fall into three categories: the request never reaches the intended resolver, the result is correct but routed incorrectly, or the resolver is reachable but returns an unsuitable result for the current network. During troubleshooting, use system tools to confirm that the domain resolves, then check whether client logs record the DNS request and route match. Do not rely only on clearing the browser cache; the operating system, client, and browser may each maintain a separate cache.

Global Proxy vs. Rule-Based Proxy

Global proxy mode generally sends all capturable traffic through the active proxy outbound, making it useful for briefly testing a node. If global mode works but rule-based mode does not, the likely cause is routing rules, DNS, or match order. It is not a universal default: LAN traffic, system updates, and local services may need direct access. After testing, return to a reviewed rule-based mode.

Rule-based proxying selects an outbound according to domains, addresses, ports, network types, or process conditions. The more rules you add, the higher the maintenance cost. Keep only rules with a clear purpose and add notes for custom entries. Before deleting a rule, confirm that no other item depends on its outbound tag. Client or subscription updates should not normally overwrite separately saved routing, but importing a full configuration may replace current settings, so export a reversible copy first.

To determine which entry point a request actually uses, watch the core access log and compare it with the app’s proxy settings. No connection record means the problem is between the app and local entry point; an inbound record without a remote connection points to routing or outbound configuration; a remote connection that fails during the handshake calls for checking node parameters, system time, and network reachability. This layered approach is faster than repeatedly switching modes.

08 / TROUBLESHOOTING

Common Configuration Issues: Diagnose Layer by Layer

Record the Symptom, Then Narrow the Fault Layer

Before troubleshooting, record four facts: the platform and client, whether you use system proxy or TUN, whether every node is affected, and the first clear error in the logs. “It does not work” is not enough: startup failure, DNS failure, remote handshake failure, and one app bypassing the proxy require entirely different paths. Change one setting at a time and retest so multiple changes do not hide the cause.

The shortest diagnostic path is: confirm ordinary networking works; confirm both the client and core processes are running; confirm the local listener exists; confirm the active node is selected; confirm the system proxy or TUN is working; then check the remote handshake and route match. If every node fails, prioritize the local network, time, DNS, subscription, and client configuration. If only one node fails, compare its address, port, transport, and security parameters with a working node.

The Core Exits Immediately After Startup

Core startup failures usually state the cause near the beginning of the log. A port conflict means the local listener cannot bind; a configuration parsing error means the generated JSON has invalid fields, commas, or types; a missing required parameter often means a security-layer field was omitted during manual node editing; permission denial commonly involves a TUN interface or protected directory. Start with the first error; later messages may only be cascading effects.

For a port conflict, exit duplicate clients or change the listening port. For a configuration error, revert the latest manual change or create a minimal node for comparison. Do not delete the log and keep only its final line; the configuration path and exact field are often shown earlier. See how to locate core startup failures in logs for a line-by-line guide.

The Client Says Connected, but Pages Do Not Open

“Connected” may only mean that the client state changed to running; it does not prove that the browser reached the local proxy. Check the system proxy address and port first, then make sure the browser has not overridden system settings. In TUN mode, inspect the virtual interface and default route. If the logs contain no browser request, the break is between the app and local entry point; if they show DNS failure, inspect the resolution path; if remote dialing times out, check the address, port, and network reachability.

If global mode works but rule-based mode does not, restore the default routing rules or review the order of custom rules. If addresses work but domains fail, temporarily disable Private DNS, browser Secure DNS, or custom system resolvers for comparison. If only LAN targets fail, add direct rules for private addresses instead of disabling all routing. See the step-by-step checks for web access after connecting.

Subscription Update Fails or Returns an Empty List

First confirm that the subscription URL is complete and contains no spaces, line breaks, or expired parameters. Then check whether the current network can reach the subscription service, whether the system clock is correct, and whether the client is mistakenly trying to update through a local proxy that has not started. With multiple groups, verify that the update targets the correct group and disable list filters to view the raw result. If content is returned but parsing fails, check compatibility between the subscription format and the client.

A smaller node list after an update may simply reflect changes to the remote subscription, not client-side deletion. Keep custom nodes in a separate group. To test the client’s parsing ability, import one clearly compatible single-node configuration. If the single node works but the subscription fails, focus on subscription retrieval or format; if the single node also fails, return to the core logs.

TLS, Server Names, and System Time

TLS errors must be interpreted alongside the exact message. For a certificate that is not yet valid or has expired, check the system date, time, and time zone first. For a server-name mismatch, verify that serverName or SNI in the node matches the service configuration. A handshake that closes early may also result from the transport path, port, or server status. Do not treat “skip certificate verification” as a standard fix; it hides identity problems and does not correct a wrong address, server name, or clock.

REALITY also requires the public key, short ID, server name, and fingerprint to match one another. Omitting any one of them when copying a node can break the handshake. For subscription-managed nodes, update the complete configuration instead of guessing fields from another node. See TLS handshake, SNI, and time checks for more details.

Return to a Testable State

When repeated changes make the source of a problem unclear, perform a controlled rollback instead of deleting everything. Export the manual nodes and rules you need to keep; disable TUN, custom DNS, and extra routes; restore system proxy mode; enable only one subscription and one node; then restart the client and watch the complete log from startup through the first request. Once the minimal state works, restore settings one at a time and test after each change.

Apply the same principle before updating the client: record the current working mode, stop the running core, save custom configuration, and install the package for the correct platform and architecture. After updating, verify the basic path before changing everything else. If the interface launches but the old configuration behaves oddly, inspect migration logs and file permissions. On Linux, check configuration-directory ownership; on Windows, check duplicate processes; on macOS, check residual network-service proxy settings; on Android, check VPN authorization and background restrictions.