Install on Any Platform
and Set Up Subscriptions

Preparation and Configuration Basics

Start by understanding the client, core, subscription, and system traffic capture as separate layers. The client provides the interface, saves groups, and generates configuration; the core handles connections and routing; the subscription URL fetches server settings; and the system proxy or virtual network adapter directs app traffic to the core. Each layer can fail independently. An open window does not mean the core has started, and a successful subscription update does not mean your browser is using the proxy.

Check Your OS, Architecture, and Download

Open your device’s system information and note the operating system, processor architecture, and available storage. Don’t guess a desktop device’s architecture from its appearance; the same model may use different chips. On the client downloads page, select your platform first, then choose the matching package. The Windows desktop and WPF editions have different interfaces; macOS downloads are available for Apple Silicon and Intel; Linux packages also vary by format.

On Android, choose the arm64 package that matches your device. If you can’t confirm its architecture, check the universal build instructions. A package downloading successfully doesn’t guarantee that your system can run it; check the download page and installer for minimum system requirements. If the architecture doesn’t match, return to the download page and choose another package instead of repeatedly changing proxy settings. Handle installation errors separately from connection problems.

Get Your Subscription URL and Check Access

Copy the complete subscription URL from your existing service’s account page. Check that your account is active, your plan allows use, and you haven’t reached the device limit. This site explains configuration but does not provide subscriptions. Subscription URLs often contain account credentials, so don’t post them in public forums. Before sharing a screenshot, hide the URL, QR code, and any sensitive personal notes.

Know the difference between a subscription URL and a single-node share link. A subscription usually fetches a set of configurations over the network; a single-node link contains the settings for one server. Pasting a single-node link into a subscription URL field may cause a format error. Using an account management page as the subscription URL may return a webpage instead of node data. Use the client subscription link explicitly provided by your service.

Check the URL for spaces, line breaks, or non-ASCII punctuation at either end. Keep the entire address, including any query parameters after the question mark. Don’t remove parameters to make the URL look shorter, and don’t paste subscription credentials into online conversion tools. Before converting formats, check who provides the tool, what it will be used for, and whether it sends the full URL to a third party.

Change One Setting at a Time

Enable automatic time synchronization, then check your device’s date and time zone. Certificate checks and some protocol authentication depend on the correct time; manually changing the clock isn’t a fix for connection errors. Make sure you’ve completed any required network sign-in. On hotel, campus, and guest networks, an unaccepted login page can make the client time out, which may look like a subscription or server problem.

Temporarily quit other proxies and tools using virtual network adapters, and note your original settings. For the first test, use one client, one server, and one traffic-capture method. Import the subscription, confirm the core starts, enable the system proxy, and try TUN only afterward. This makes it clear which step changed the outcome instead of leaving you to untangle several rule layers at once.

Choose two test destinations with clear purposes: a site that should connect directly and a service that should use the proxy under your current rules. A cached browser page doesn’t prove the connection works; make a fresh request and check the client logs. Don’t judge every app by the test result beside a server, either. That result usually reflects only one type of probe.

Finally, check the requirements for your work network or managed device. Organization-managed devices may restrict local proxies, network extensions, or administrator access. If a policy explicitly blocks a feature, contact your device administrator. Don’t bypass restrictions by disabling system protections. The platform sections below follow the same sequence: download, install, import, route traffic, and verify. Move on to the next step once each one works.

Windows: Install v2rayN

On Windows, choose v2rayN from the Windows downloads. The desktop edition uses a cross-platform interface, while the WPF edition retains the classic desktop experience. Choose whichever suits your workflow; you don’t need both just to import a subscription. The steps below refer to features such as “subscription groups” and “system proxy”; their exact menu locations may change between versions.

Install the Client and Check That the Core Starts

When running the installer, check that the destination folder is writable. If you downloaded a package that needs extracting, extract the entire archive before launching the app from its destination folder. Don’t run it from the archive preview or drag out only the main executable. Supporting files and configuration may rely on relative paths; missing files can let the window open while preventing the core from starting.

When you first open the client, check the log area for missing components, configuration parsing errors, or port conflicts. If the app reports a missing runtime, install the component required by that build, then restart the client. Don’t copy a similarly named dynamic library from an unknown site into the app folder. That won’t ensure the dependency is compatible and will make it harder to troubleshoot against a clean installation.

You normally don’t need administrator privileges for the system proxy. Start by importing your subscription and testing in a browser as a regular user. Elevate permissions only when prompted for a feature that requires it. If your configuration list is empty when you run as administrator, check whether you’ve launched another copy or a different configuration directory. Don’t immediately import again and overwrite existing data.

Add a Subscription Group and Update Servers

Open the subscription group settings and create a group. Add a recognizable note describing its purpose, then paste the full subscription URL into the address field. Enable updates for the group, save it, and then select Update subscription. The automatic update interval controls future refreshes; it doesn’t replace the first manual update. Keep the default User-Agent for the first update unless your provider explicitly requires a different value.

When the update finishes, return to the server list and check that no other group or search filter is hiding the results. Select a server and set it as active, then check the logs for a newly generated configuration. If the subscription contains fields unsupported by the current core, server names may still appear while startup fails. Check protocol and core support rather than repeatedly copying the URL.

If the client offers direct and proxied subscription updates, first try the method accessible on your current network. A proxied update requires an existing working connection; it can’t restore a subscription when every server is unavailable. Keep the original group, review the update response, and then decide whether to change the retrieval method. Don’t delete all servers first and lose a working recovery path.

Set the System Proxy and Check the Port

Choose the option to configure the system proxy so apps that follow the Windows proxy settings use the client’s local listening address. Open Windows proxy settings and check that the manual proxy address and port match the client’s current settings. The local listening port is not the remote server port or the port in the subscription URL; these have different purposes and must not be substituted for one another.

Keep the routing mode on a preset that suits your needs, then make a fresh browser request. If it still fails, check for a proxy extension that overrides system settings or a different proxy configured in the browser itself. Which apps use the system proxy depends on the app; one program connecting directly doesn’t mean the core has failed. To capture traffic from apps like these, see System proxy and TUN.

Handle Windows-Specific Exit and Permission Issues

Before enabling TUN, save any active network work and follow the client’s prompts to elevate permissions. A failed virtual adapter and an unreachable server are different problems: check permissions, drivers, and conflicting network tools for the former; check the server and routing for the latter. Don’t reinstall the client, remove network adapters, and reset the system network all at once. Start by preserving the exact error message.

Before quitting the client, clear the system proxy, then close the app. If it closes unexpectedly and your browser can’t connect, open Windows proxy settings and check whether they still point to a local port that is no longer listening. Clear any stale manual proxy and test a direct connection. If that restores access, the problem is the traffic-capture state; there’s no need to change the subscription or delete all your settings.

When configuring startup, distinguish between launching the app and automatically enabling traffic capture. Verify what happens after one restart before deciding whether to connect automatically. On a shared PC, check proxy settings under the account that will actually use the client. To move your configuration, quit the client and make a backup first; don’t overwrite files between two running instances.

macOS: Install and Grant Network Permissions

On macOS, open About This Mac to check your chip before downloading v2rayN. Choose the Apple Silicon build for an Apple chip or the Intel build for an Intel processor. Select the matching package in the macOS downloads. Architecture affects whether the app runs, not the contents of your subscription, so don’t try to fix a startup error by changing protocols.

Install the App in a Stable Location

Open the disk image and follow the installer’s instructions to move the app into Applications. Launch it from there rather than running it from the mounted image or a temporary downloads folder. A stable install location helps macOS identify permissions and startup items, and reduces the chance of opening an old duplicate or losing track of the configuration after an update.

If a security prompt appears on first launch, verify the installer source and app name, then check Privacy & Security in System Settings for an available approval option. The exact location may vary by macOS version; follow the prompt shown on your system. Don’t disable system security across the board or run terminal commands from an unknown source just to dismiss a warning.

After launching, check the logs to make sure the core loaded. If macOS says the app can’t run, check system requirements, chip architecture, and whether installation is complete. If the window opens but the core reports an error, investigate the specific component or configuration issue. Separating these stages helps prevent a compatibility problem from being mistaken for an unavailable subscription service.

Import a Subscription and Make Your First Connection

Add a group in the subscription settings, enter a note and the full URL, save, and update it manually. When pasting, check whether the clipboard content came from a password manager or rich-text page, and remove any trailing spaces. After the update, select an active server and keep its default connection parameters. Don’t change the subscription’s transport, service name, or certificate fields without a specific reason.

If the update returns several similarly named servers, use your provider’s instructions to choose the right one; identical names don’t guarantee identical configurations. Subscription updates may replace server parameters, and your manual changes may be overwritten on the next update. For persistent custom settings, use a separate group or a client-supported persistent rule, and record why you changed it.

Check Proxy Status for the Current Network Service

After enabling the client’s system proxy, check proxy settings in the details for the current network connection. macOS proxy configuration is associated with a network service, so Wi-Fi and Ethernet may have different settings saved. If the browser stops using the proxy after connecting a dock or switching networks, first check which network service is active rather than immediately changing servers.

Understand the Web Proxy, Secure Web Proxy, and SOCKS proxy fields separately. If the client configures some of them automatically, keep them consistent with its listening mode. Don’t enter the same port in every field just to “select all.” Apps with manual proxy settings need the correct HTTP or SOCKS type; a type that doesn’t match the listening port will usually fail immediately.

Once the browser test works, check the apps you actually need. Some follow the system proxy, some use their own network settings, and others read the settings only at launch. After changing the proxy, quit and reopen the target app, then check whether the logs show a request. Don’t assume the new settings failed just because the app is reusing an existing connection.

Use TUN Only If Needed, and Verify Recovery

If your build includes TUN, follow the client’s prompts to grant the required permissions, then check the logs for virtual interface and route initialization. Don’t try to add unavailable options by copying commands from another platform. Consider TUN only when the system proxy can’t cover a target app; everyday browser use doesn’t require an extra traffic-capture layer.

If the connection stalls after waking from sleep, pause and re-enable traffic capture, then check whether the network itself is back. Waking can change the device’s address, gateway, or DNS; a stale connection doesn’t mean the subscription needs updating. If this happens after every wake, note whether it occurs only with TUN, a particular network service, or a specific app to narrow down the cause.

Before quitting or uninstalling, turn off TUN and the system proxy, then check the current network service for leftover settings. Test a direct connection and confirm access is restored before removing the app. Back up any configuration you need to keep, but don’t share the entire configuration directory publicly. For recurring disconnects after network changes, see Troubleshooting for permission and traffic-capture conflicts.

Linux: Packages and Desktop Proxy

On Linux, check your distribution’s package system and device architecture, then choose v2rayN from the Linux downloads. Debian-based distributions commonly use deb packages; RPM-based distributions use rpm. Either format may come in x64 or arm64. A desktop client also needs a working desktop environment; successfully unpacking a package doesn’t mean the graphical app has everything it needs to run.

Install with Your Distribution’s Package Manager

Use your distribution’s software installer to open the downloaded package so the package manager can handle dependencies. If the installer reports missing dependencies, check which ones and whether they’re supported by your system version, then resolve them through the distribution’s standard software sources. Don’t mix repositories from other distributions or force installation while ignoring dependencies; that can leave the app unable to start or cause system component conflicts.

Check the architecture with the command below. It only displays your machine type and doesn’t change system settings. The common output x86_64 corresponds to x64 packages; aarch64 corresponds to arm64. If you’re using a container, remote desktop, or compatibility layer, distinguish the host system from the actual runtime environment. Don’t choose a package based only on the host hardware name.

uname -m

After installation, launch the app from the desktop menu as a regular user. If the window won’t open, launch the installed program from a terminal to read the error, but don’t run the entire graphical client as an administrator to bypass it. Regular and administrator accounts use different configuration directories; mixing them can create mismatched subscriptions, permissions, and file ownership that are harder to maintain.

Import a Subscription and Check the Local Listener

Open subscription groups, add a note and URL, save, update, then select an active server. Configure the desktop proxy only after confirming the core has started. If the logs show a port conflict, quit other proxy apps and duplicate instances first. For common example ports, use the command below to check what’s listening. If your local settings use a different port, replace it with the actual value.

ss -ltnp 'sport = :10808'
ss -ltnp 'sport = :10809'

No output may mean nothing is listening on that port, or that the client is using a different one. Details about some processes may also require additional permissions. Check the client settings instead of assuming the example port is correct. For ordinary local use, bind to the loopback address. Consider listening on the local network and adjusting firewall rules only when other devices specifically need access.

Desktop Proxy and Terminal Environment Variables Are Different

Desktop environments handle system proxy settings differently, and the client’s automatic configuration may not cover every app. After enabling the system proxy, check its mode and port in the desktop network settings, then test with a browser. A tray icon doesn’t prove that the core is working, either. If tray support is unavailable, check the app window and logs.

Terminal apps often have their own proxy handling and may ignore desktop settings. To test one, specify a proxy for that command instead of changing the entire login environment. The example below assumes HTTP listens on 10809 and SOCKS on 10808; check your actual ports first. A successful request to a webpage doesn’t prove that every application protocol works.

curl --proxy http://127.0.0.1:10809 --head https://example.com
curl --proxy socks5h://127.0.0.1:10808 --head https://example.com

In the second command, socks5h means the proxy resolves the destination hostname, unlike some local DNS resolution methods. If the terminal test succeeds but the browser fails, check the desktop proxy or browser settings. If both fail, check the listener, active server, and logs. A terminal that already has proxy environment variables may still point to a local port even after the desktop proxy is turned off.

Use Care with TUN, Permissions, and the Default Route

Enabling TUN depends on the client build, system capabilities, and permission model. Follow the instructions shown in your client. If virtual interface creation fails, check whether the logs point to permissions or device support. Don’t permanently run the entire app with elevated privileges. On a remotely accessed device, keep a recovery path: changing the default route may disconnect your current session.

If you use another VPN, container network, or firewall management tool, check which routes and rules each one manages. Don’t flush the system firewall to try to restore a connection; that could disrupt other services. Quit the client, test a direct connection, and check for leftover desktop proxy settings or terminal variables. If needed, open a fresh terminal session and test again.

Back up subscription groups and custom rules before upgrading, and update using the same package management method. If only the interface is broken after an update, record the desktop environment and error output before considering configuration changes. If the core can’t parse its configuration, check whether custom parameters are still supported. Keep GUI, package, and network issues separate to identify which layer needs rolling back.

Android: Subscription Setup and VPN Permission

On Android, start with v2rayNG, which uses the Xray core. If you need the V2Fly core and your configuration supports it, v2flyNG is an alternative. In the Android downloads, choose the arm64 package for your device; if you can’t confirm its architecture or your device is unusual, check the universal build. Don’t run both clients’ connection services at the same time just to compare their interfaces.

Install the App and Grant System Permission

When you open the downloaded file, Android may ask you to allow app installs from that source. Verify the source, then grant permission only to the browser or file manager you’re using, as needed. If installation fails, check the system message: low storage, architecture mismatch, system requirements, and a signature conflict with an existing app each need a different fix. Reimporting the subscription won’t resolve them.

If an app with the same name is already installed, don’t uninstall it without a backup. First check whether an in-place update is possible and whether your subscription and rules are saved. If Android reports a signature mismatch, verify the download source and stop; don’t mix builds. Uninstalling may delete app data, and a server name alone can’t restore the full subscription URL or local settings.

Create a Subscription Group and Select an Active Server

Open subscription settings, add an entry, enter a note and URL, enable updates, and save. Then update the subscription. Some interfaces separate the server list from subscription management, so confirm you’re updating the right group. If your clipboard contains a single-node share link, use the appropriate import option instead of pasting it into a subscription URL field that fetches data over the network.

After a successful update, return to the list, select an active server, and start the connection. The note is only a label; it isn’t used for authentication. The address, port, user ID, transport, and security parameters must match the server. A name that suggests a particular use doesn’t mean the server supports every protocol or app. After your provider updates the subscription, check that the active server is still listed.

“Allow insecure connections” is not a general fix for network errors. If you see a certificate error, first check the system time, destination hostname, and provider instructions, and keep certificate verification enabled. Turning off verification at random changes the connection’s security boundary and won’t fix an expired address, blocked port, or disabled account.

Understand Local VPN Traffic Capture and App Scope

The first time you connect, Android usually displays a VPN connection request. Verify that it was initiated by the client you just installed, then grant permission. This allows the client to establish a traffic-capture tunnel on your device; it doesn’t confirm that the remote server is reachable. Even after the system shows a VPN indicator, make a real request and check the app logs to confirm the core completed the connection.

Android’s local VPN mechanism works differently from the system proxy on desktop; you don’t need to copy fields from the Windows proxy settings. Android generally allows only one VPN service of this type to be active at a time, so other network tools using the same mechanism may take over the connection. If it disconnects automatically, first check whether another service has started rather than deleting your subscription.

If per-app proxying is enabled, check whether the current mode means “only selected apps use the proxy” or “selected apps bypass the proxy.” These lists do opposite things. Misunderstanding them can make the browser work while other apps fail. After changing the scope, reconnect and reopen the target app. If needed, first test with a baseline configuration that doesn’t filter apps.

Check Network Changes, Sleep, and DNS

After switching from Wi-Fi to mobile data, the existing connection may need to be re-established. Confirm that mobile data works, then reconnect the client. If Wi-Fi works but mobile data doesn’t, note the network differences and check for IPv6, destination port, or DNS path issues. Don’t treat automatic reconnection as unlimited retries; if it keeps failing, pause and check the first relevant error.

Private DNS, an app’s encrypted DNS, and client DNS can all be configured at once, but they may not do the same job. If a hostname fails while other requests work, note these settings and test them one at a time. Don’t change every DNS setting at once; even if the connection recovers, you won’t know which change made the difference.

Finally, test what happens after you disconnect. If Always-on VPN or Block connections without VPN is enabled, direct access may remain blocked after the client stops; that’s the system policy at work. Keep or change the setting as needed, but don’t mistake it for a broken network. Before switching clients, stop the old service, install the new app, and test protocol support and background stability separately.

System Proxy, TUN, and Traffic Capture

Choose a traffic-capture method based on how the app sends traffic. A system proxy tells apps where the proxy endpoint is, but each app decides whether to use it. TUN uses a virtual network interface and routes to pass matching traffic to a handler. Neither is a remote server, and neither determines whether a domain ultimately connects directly or through a proxy; routing rules make that choice.

Separate Traffic Capture from Outbound Routing

“Enable system proxy” and “use global routing” are different actions. The first determines whether an app’s requests enter the client; the second determines which outbound route they take after entering. Changing only the global route won’t redirect an app that ignores the system proxy. Enabling TUN doesn’t guarantee that every request goes through a remote proxy either; direct rules may still apply.

Options such as Clear system proxy, Set system proxy, and Do not change system proxy are different management actions. Clearing usually removes the system proxy settings managed by the client; setting writes the client’s local listening endpoint; leaving unchanged preserves the current system state. Actual behavior depends on the client. If an organization policy or manual setting is already in place, record the original values before changing anything.

Rule order, match criteria, and fallback behavior

Enable the system proxy and first confirm that a browser can reach sites. Then check whether the target app follows the setting. If it accepts a manual proxy, try the local HTTP or SOCKS endpoint to verify that the core and server work. If TUN fails afterward, you can focus on the system traffic-capture layer instead of questioning the entire subscription setup.

Before enabling TUN, close other tools that capture traffic in the same way and save your work. Grant the required permissions as prompted. After startup, check whether the interface was created, routes were added, and DNS initialized successfully. Some builds use different helper components, so don’t copy driver setup steps across platforms. If the logs stop at interface initialization, troubleshoot the local system first.

Whether to use TUN and the system proxy together depends on the client and your use case; there’s no one-size-fits-all answer. For baseline testing, keep one primary traffic-capture path. If you need both, make sure the local proxy connection isn’t mistakenly captured again. If connections loop, resource usage spikes, or the apparent exit location keeps changing, switch back to one path and test it on its own.

Check UDP, Local Network, and Virtual Networks

A successful webpage test doesn’t prove that a UDP app will work. The target app must use UDP, the chosen protocol and server must support it, and the client’s inbound path must capture it. Don’t switch to global routing just because UDP fails; routing rules choose an outbound path but can’t add a capability the server doesn’t offer. Check the service documentation first, then inspect the connection type in the logs.

Printers, file shares, and local network admin pages usually need a route that remains reachable locally. If they stop working after enabling TUN, check whether local network addresses are being sent to a remote server, then review the client’s exclusion rules. Organization networks may use multiple private subnets; covering only your home router’s subnet won’t account for all of them.

Virtual machines, containers, and other VPNs may also add network interfaces, DNS settings, and routes. If they conflict, note which network tools are running and pause them one at a time to test. Don’t delete every route. Take particular care with remote work or device administration: before changing traffic-capture rules, make sure you have a local recovery method so you don’t cut off the route sustaining your session.

Trace the Request Path to Diagnose the Result

During testing, check the app, listening endpoint, matched route, and remote connection separately. If no request appears in the logs, focus on traffic capture. If a request appears and matches a direct route, check the rules. If it matches a proxy route but times out, investigate the server and network next. For details on when to enable it, see the v2rayN TUN mode guide; TUN isn’t a universal fix for connection problems.

After disconnecting, test the same app again and confirm the result is as expected. Browsers can reuse long-lived connections, and some apps keep their own connection pools, so you may need a fresh request to see the new route. Record a working baseline, then add startup behavior, per-app scope, or complex exclusions one at a time. It’s easier to maintain than enabling everything at once.

Split Routing and DNS

Routing chooses an outbound path for requests that have reached the core; DNS resolves domain names to addresses. They affect each other, but they aren’t the same thing. Start by defining your goals: which services should connect directly, which should use a proxy, and which should be blocked. Then choose a suitable preset. Don’t replace your current configuration wholesale with a large rule set from an unverified source.

Start with a Stable Preset

Names such as Global, Bypass mainland China, and Blacklist refer to client presets; their actual rules may vary with rule resources and settings. Global generally sends ordinary destinations through the proxy but may retain necessary local exceptions. Bypass mainland China depends on domain and IP classification. Check what the Blacklist preset actually contains rather than guessing from its name where every destination will go.

After changing presets, send requests to your prepared direct and proxied destinations and check which routes they match. Don’t test only the exit IP; it reflects just that request’s path. An app may contact separate domains for sign-in, content, and updates. If the home page works but one feature fails, inspect that specific request instead of immediately switching the entire configuration to global routing.

Understand Rule Order and Domain Matching

Most rules are checked in order, and the first match determines the route. Place an exception for a specific destination before any broader rule that would catch it. Domain rules are usually easier to maintain than pinning a rule to a resolved IP, since service addresses can change. But if an app connects directly to an IP address, a domain rule may not match; check that separately.

The Xray-style routing snippet below shows how to send private IP addresses and selected domains directly. It isn’t a complete runnable configuration; outbound tags must match your existing setup. GUI clients usually generate the configuration, so use their routing editor to express the same rules when possible. Don’t overwrite the runtime file directly; the client may regenerate it at the next launch.

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

The domain matcher can cover a specified domain and its subdomains; use full for an exact hostname if appropriate. geosite and geoip depend on the corresponding resource files, and the category names must exist. AsIs doesn’t mean “never resolve domains.” It describes the routing-stage policy; other connection and DNS stages may still resolve names. A single field can’t tell you the full request path.

Check Destination DNS and Server DNS Separately

The client may need to resolve both the destination domain you visit and the proxy server’s own hostname. If resolving the latter depends on a proxy connection that hasn’t started yet, startup can get stuck in a loop. If resolution keeps failing during initialization, identify which hostname is affected. Don’t force every DNS request through a proxy that isn’t available yet.

The system, browser, and client may all have DNS settings. If the browser uses its own encrypted DNS, the expected system DNS request may not appear in the client logs. With TUN enabled, the client may also capture some DNS traffic. Troubleshoot by tracing who makes the lookup, who returns the result, and which route the request takes, then decide which layer to adjust.

After changing routing or DNS, old cache entries and existing connections may remain in use. Make a new request and, if needed, restart the target app. Don’t keep adding rules just because one page refresh didn’t change anything. Stacking temporary changes can hide the real DNS issue beneath complex routing, making it harder to know what to keep when restoring the configuration.

Check IPv6 and Split-Routing Boundaries

On networks with both IPv4 and IPv6, apps may prefer different address families. If a domain works intermittently, note the destination address in the logs and check that each route works. Temporarily restricting an address family can help isolate the issue, but don’t disable IPv6 permanently without understanding the cause, especially on networks that depend on it.

Internal organization domains usually need the organization’s DNS resolver; public resolvers may not know internal records. If an intranet site won’t open, check both DNS resolution and the internal route instead of adding only a direct-connection rule. A successful DNS lookup doesn’t guarantee the route is reachable, so verify both stages separately.

Add one rule at a time, with a clear purpose, and note why you added it. Keep a copy of the previous configuration. Start with split routing for mainland China and international traffic to establish a baseline, then handle exceptions with custom routing rule syntax. Specific rules are easier to test and make it easier to find what needs updating when service addresses change.

Common Configuration Issues and Troubleshooting

Start troubleshooting by describing what happened, then decide what to change. Note the platform, client, traffic-capture method, active server, and action that triggered the error—for example, “subscription update failed” or “the intranet became unreachable after enabling TUN.” “It doesn’t connect” isn’t enough: subscription retrieval, core startup, traffic capture, and remote access are different stages and require different evidence.

Subscription Update Failed or No Servers Listed

First check that the URL is complete and the account is active. Then check whether the update returned a network error, webpage content, or a parsing error. For a network error, check the retrieval path. Webpage content may be a sign-in or error page. For a parsing error, check the subscription format and client support. A response doesn’t necessarily contain a valid subscription; “download complete” alone isn’t proof.

If the list is empty after an update, clear any search filters, switch to the intended group, and confirm that updates are enabled for it. Keep the pre-update configuration instead of repeatedly deleting and recreating the group. If only some servers disappear, the provider may have changed the subscription or some configurations may not parse. Note the omitted types and error messages, then compare them with the service documentation. Don’t invent node settings manually.

Core Won’t Start or Local Port Is Unavailable

Find the earliest relevant error from the current startup. For a port conflict, check for duplicate instances; for a configuration field error, undo the latest change; for a missing file, check that installation completed. Many later connection failures may follow from the first startup error. Fixing each subsequent timeout won’t help if the core never started.

If you have multiple distribution formats installed, check which executable path is running. You may have changed settings in one copy while launching another. After an upgrade, don’t immediately overwrite the new app with the entire old directory. First verify that it starts, then restore configuration using a method supported by the client. Treat the executable, runtime components, and user settings as separate things; not every file is configuration.

Browser Works but Other Apps Fail

Check whether the target app reads the system proxy and whether it has its own proxy or per-app exclusion. If there’s no matching request in the logs, start by checking the path from the app to the client. If the request appears and matches a proxy route, check the protocol, remote connection, and app-specific behavior. If you need TUN, enable it step by step as described in the previous section. Don’t start by changing authentication fields in the subscription.

If web pages work but voice, games, or real-time features fail, check UDP and service support; a browser test doesn’t verify other protocols. Failed downloads may also involve an app-specific network stack or several domains. Note the specific failing feature and time, then check nearby log entries. This is more useful than repeatedly switching servers.

Handshake Errors, Timeouts, and Partial Failures

For certificate or handshake errors, check the system time, server name, and subscription first, then confirm that the current core supports the required parameters. The public key, server name, and related identifiers in a REALITY configuration must match the server. Don’t replace them based on guesswork. If the provider has changed server parameters, update the subscription and ask them to confirm rather than disabling security checks.

For a timeout, distinguish between an unreachable server address, a timed-out destination request, and a DNS timeout. If the problem occurs only on one network, note the differences between Wi-Fi, mobile data, and Ethernet. If only one server fails, compare it with another using the same traffic-capture and routing settings. Keep other conditions fixed so the comparison is meaningful and the result can be interpreted.

Save Evidence and Restore a Working Baseline

When preparing a report, keep the error time, steps to reproduce, and a redacted log. Remove subscription URLs, user IDs, QR codes, and account details. Destination domains in logs may also reveal personal browsing activity, so redact them as appropriate. Don’t bundle your entire configuration directory for support, and never upload a backup containing credentials to a public location.

To restore a working setup, undo the most recent change and return to a baseline with one client, one server, and one traffic-capture method. Keep a brief note of what worked, then restore custom rules and automatic startup one at a time. For everyday issues, see Troubleshooting. To repeat the setup steps, return to the quick start guide; there’s no need to reinstall everything first.