Setup for Every Platform

Before you begin

Know the difference between clients, cores, and connection details

The client provides the interface, subscription management, and system settings. The core handles connections, protocols, and routing. For desktop, v2rayN is the recommended choice; on Android, v2rayNG with the Xray core is generally preferred. Consider v2flyNG when you need compatibility with the V2Fly core. Installing a client does not provide a working server: before you start, prepare a subscription URL, a single share link, or a complete configuration you are authorized to use, along with the protocol and transport requirements from your provider.

First, identify the connection details you have. A share link beginning with a protocol name usually represents a single server entry. A regular web address may be a subscription endpoint or simply a management page; these are not interchangeable. A complete JSON configuration may include inbound and outbound settings, routing, and DNS, so it should not be pasted into a subscription URL field. Checking the format before importing is more useful than repeatedly clicking Update. For details on entry points and formats, see the subscription import guide.

Subscription URLs often contain access credentials and should be treated like account information. Do not share the full URL in public screenshots or submit it to an untrusted website for conversion. When reporting an issue, include only the protocol, transport, and error message; remove URL query parameters, user identifiers, and passwords. To move to another device, use the client's export feature where possible, and check whether the export contains only server entries or a full backup with local settings.

Check your architecture, network, and permissions

Open your system's device information and note the operating system, processor architecture, and package type. For desktop downloads, x64 and arm64 refer to processor architectures; do not infer yours from the computer brand. On macOS, check the chip under About This Mac. On Linux, check the architecture in the system's About settings. The arm64 package works on most newer Android devices; if you are unsure, start with the universal package. Find all installation packages on the client downloads page; this guide does not provide duplicate download links.

Before troubleshooting, quit other proxy or tunnel apps so only one traffic-handling method is active. Make sure your regular internet connection works, complete any browser-based network sign-in, and check that the system date, time, and time zone are correct. An incorrect clock can cause TLS certificate verification failures; an incomplete network sign-in can redirect subscription requests to a login page. Both can look like configuration problems, but should be resolved outside the client first.

Test a regular proxy and TUN separately. A regular proxy usually changes system proxy settings or provides a local listening port. TUN also involves a virtual network interface, routes, and DNS, and may require administrator permissions or a helper service. Verify the regular proxy first, then enable TUN to distinguish server connectivity issues from system traffic-capture issues. Avoid changing the core, DNS, routing, and permissions all at once; even if the connection comes back, you will not know which change fixed it.

Establish a baseline you can restore

Note the local listening addresses and ports. A common example is SOCKS at 127.0.0.1:10808 and HTTP at 127.0.0.1:10809, but use the current client settings and startup logs as the source of truth. Some builds use a mixed port rather than separate listeners. Loopback addresses are accessible only from the local machine and are suitable for an initial setup. Unless you have a specific need, do not listen on all network interfaces or open inbound firewall rules.

After installation, save a known-working configuration before updating subscriptions or changing rules. At minimum, record the active server, core type, local ports, system proxy status, routing mode, and TUN setting. Keep backups in a restricted folder. To restore one, quit the client first and use its backup or import mechanism to avoid the running process writing the old state back. When moving between devices, do not assume the configuration directory, permissions, or absolute paths will be identical.

Do not judge success by whether a button changes color. Check, in order, that the logs show no startup errors, the application is using the current local port, the target request appears in the connection log, and the system network recovers after you exit. A client connection test reflects only its specific probe method; it cannot replace a browser test or a check in the application you actually use. Once these checks pass, continue to the relevant platform section. This makes it easier to identify whether a later issue involves installation, importing, the core, or traffic handling.

Set up V2Ray on Windows

Choose the desktop or classic WPF edition

Go to the Windows downloads and choose v2rayN. The desktop edition uses a cross-platform interface, while the classic WPF edition follows Windows UI conventions. Their menus, configuration directories, and feature locations may differ; do not run both at once to compare behavior on the same port. For help choosing between them, see Desktop vs. WPF editions. Choose one, complete the basic setup, and confirm it works before considering a migration.

Follow the installer prompts to choose a folder and shortcuts. Before upgrading an existing installation, quit the client from the system tray and back up your subscriptions and local settings; closing the main window may not stop its background process. After installation, launch the app from the Start menu and check the logs for missing runtime components, core files, or rule resources. If Windows displays a security warning, verify the file's source and publisher instead of disabling system protections to get past the startup issue.

The configuration and installation directories may be different, so do not treat the installation folder as the only place to back up. Use the interface's Open configuration folder or backup settings option if available. If you see a “Cannot write configuration” error, check that your account can write to the directory and that sync software or Controlled Folder Access is not blocking it. Routine use should not require running as administrator. Elevate permissions only when the interface specifically requires it to install a service or configure TUN.

Import a subscription and select an active server

In v2rayN, open Subscription Group Settings, add a group with a recognizable name, and paste the subscription URL into the appropriate field. For the first import, leave Filter keywords empty. Save the group, return to the main window, update subscriptions, and select the group. A successful update means the data was fetched and parsed; you still need to choose a server in the list and set it as active. If double-clicking a server only opens an edit window, close it and check whether the active indicator actually changed.

If the menu offers updates through or without a proxy, try without a proxy first when you do not yet have a working connection. Once you have a usable connection, try updating through the proxy if the subscription endpoint requires it. Do not assume every update failure is a client issue: distinguish a timeout, a webpage response, expired authorization, and a parsing error. Being able to open the subscription management page in a browser does not mean the subscription endpoint returns data the client can interpret.

When adding a server manually, use the protocol, address, port, user ID, transport, and TLS settings from the same connection profile. Do not combine a sample transport path with another server's port. After saving, check that the selected core supports the combination, especially if it uses features such as REALITY. Subscription updates may rebuild server entries, so copy a server to a separate group before making temporary changes to avoid losing local edits on the next update.

System proxy, TUN, and restoring settings on exit

Once the core is running, set System proxy to “Set system proxy automatically.” This typically points Windows proxy settings to the client's local listener, but not every application follows those settings. Browsers usually use the system proxy; command-line tools and apps with their own network stack may need separate configuration. If an app asks for a SOCKS address, enter the actual SOCKS listening port. Do not swap HTTP and SOCKS just because their port numbers are close.

If you need to capture traffic from applications that ignore the system proxy, consider enabling TUN mode. Support depends on the selected build, its backend, and the required permissions; checking a box does not give every core the same capabilities. Follow the interface prompts to install or start required services, then check that the virtual adapter, routes, and DNS are set up successfully. For the first test, keep the default traffic-handling settings. Corporate networks, virtual machines, and other tunnel apps may already have custom routes; note them first and check for conflicts one at a time.

A common false alarm on Windows is a leftover proxy setting. Before quitting the client, choose Clear system proxy, then exit normally from the system tray. If the app previously crashed, check Settings → Network & Internet → Proxy to see whether a manual proxy still points to a stopped local port. After disabling TUN, confirm that the network is working again. If a browser works but a service process does not, do not immediately reinstall the client: the service account may have different proxy settings from the current desktop user, so check the application itself.

For a final check, verify normal startup, switching servers, updating subscriptions, and restoring the network on exit. Configure startup on boot only after manual use is stable. If the network is not ready at startup, an automatic update failure does not mean the subscription has expired. Wait until the connection is up, then update manually and check the logs. If the connection fails after sleep, restart the core instead of deleting the configuration, and check for stale network interfaces or DNS settings from before sleep.

Set up V2Ray on macOS

Choose a package for your processor

Open About This Mac from the Apple menu to see whether it lists a chip name or an Intel processor, then choose the matching v2rayN package from the macOS downloads. Choose arm64 for Apple Silicon and x64 for Intel; do not guess based on the computer's appearance or size. After downloading, open the disk image, drag the app to Applications, and launch it from there. Running the copy directly from the disk image long-term can complicate updates, permissions, and identifying the app's location.

If macOS security blocks the first launch, confirm the download source and follow the instructions under System Settings → Privacy & Security to allow this app. Do not turn off system security protections wholesale or copy terminal commands from untrusted sources. If macOS says the app cannot run, check the architecture and system requirements first, then make sure the download and installation completed. Permissions, architecture, and configuration are separate issues; troubleshoot them in that order.

Before upgrading, quit the old instance from the menu bar or background, back up your settings, and then replace the app in Applications. Multiple copies in Downloads, a disk image, and Applications can cause a login item to launch an older copy. If the expected subscription is missing after launch, check which copy is running and which user account you are using before importing everything again. Configuration files usually belong to the current user; running the app under another account will not automatically share the same settings.

Import subscriptions and configure the system proxy

In v2rayN, open Subscription Group Settings, add a group with a clear name, paste the subscription URL, save it, and update subscriptions. To import a single share link, use the server import option rather than the subscription URL field. Once the list is updated, select an active server and check that the protocol is supported by the core. For the first test, leave keyword filters off; an empty list could mean the request failed, or that the filter excluded every entry.

After enabling the system proxy, open System Settings → Network, select the network service currently in use, and check the settings under Details → Proxies. The exact menu path may change between macOS versions, but the important thing is to check the active network service. Wi-Fi and Ethernet may have separate proxy settings. After switching connections, verify the proxy address and port again; do not assume that a setting which works on Wi-Fi is also applied to Ethernet.

Browsers usually follow the system proxy, but extensions or a browser's own proxy settings may override it. For troubleshooting, disable proxy extensions and check whether the app specifies a separate proxy. If an app supports only HTTP proxy, enter the actual HTTP listening port; if it supports only SOCKS, use the SOCKS port. Do not enter the remote server address in the system proxy settings. The system proxy should point to the local client, which handles the protocol handshake and routing.

TUN permissions, sleep, and network changes

TUN traffic handling depends on the helper mechanism and system permissions supported by the current build; do not apply the Windows service installation steps to macOS. Verify the connection through a regular proxy first, then follow the v2rayN prompts to grant the required permissions. An authorization prompt should match the action you just took. If permission was denied, review the relevant System Settings and restart the feature. If the interface does not provide a traffic-handling option, do not try to imitate it by changing unrelated core fields.

After waking from sleep, switching hotspots, or moving from Wi-Fi to Ethernet, existing connections may stop working. Turn traffic handling off and back on, then check the logs to see whether the client rebound to the current network; restart the core if needed. If domain names fail but existing connections still work, check DNS and the network service transition before changing servers. Corporate network auto-proxy settings may also rewrite system options; follow your network administrator's requirements and avoid two mechanisms repeatedly overwriting each other.

Before quitting normally, disable TUN and clear the system proxy set by the client. After an unexpected exit, if all browser requests fail, check the proxy settings for the active network service to see whether they still point to a loopback address. Stopping the core does not guarantee that every network service returns to its default settings. Do not delete network services to clear a leftover proxy; first remove settings clearly added by the client, and preserve the original DNS, auto-configuration URL, and network authentication details.

When troubleshooting installation paths or permissions, distinguish the main app from helper processes. A process still visible in Activity Monitor does not necessarily mean the main window is still open; conversely, a normal-looking interface does not prove that its helper component is working. Use the logs to confirm that listening ports are open, routes are established, and requests are being handled. Verify the regular proxy, any required TUN setup, and direct connectivity after quitting separately. Add the app to login items only after permissions are fully configured, rather than making an incomplete setup run at every login.

Set up V2Ray on Linux

Match the distribution and package architecture

For desktop environments, v2rayN is the recommended choice. Open the Linux downloads, choose deb or rpm to match your distribution's package system, then check whether your processor is x64 or arm64. Package format determines installer compatibility, not whether every desktop environment handles system proxy settings the same way. Check your distribution's system information before installing, and open the package with its graphical installer. If dependencies are missing, use the distribution's package manager rather than treating an unfamiliar script as a universal installation method.

After installation, launch the app from the application menu; do not run the entire graphical client as root by default. A process with elevated privileges may write its configuration to a different user's directory, making subscriptions disappear or leaving files unwritable when launched normally. If you have already run it this way, quit the app, check the actual configuration location and file ownership, and fix them using your distribution's recommended method. Do not make the configuration directory writable by every user just to get one launch working; that exposes local data to others.

If the graphical interface will not open, first distinguish a desktop session problem from a core problem. Without a display environment, graphics dependencies, or session variables, the main window may not open, meaning the app has not reached the server connection stage. If the window opens but the logs report a missing core, check that installation completed and that security policies are not blocking execution. Containers, remote sessions, and minimal desktop environments may lack full system proxy integration; the graphical steps in this guide are not a substitute for deployment instructions tailored to those environments.

Configure subscriptions and application proxies separately

Add the subscription URL in Subscription Group Settings, save it, update subscriptions, and select an active server. If the URL contains special characters, paste it in full without removing query parameters; line breaks, leading or trailing spaces, and copied webpage markup can all cause parsing failures. If the first update fails, check network authentication and the endpoint response before changing system routes. Once a working connection is available, try updating through the proxy to avoid relying on a proxy channel that is not yet established.

GNOME, KDE, and other desktop environments each provide their own system proxy settings, and applications may read different sources. After setting the system proxy in v2rayN, check the desktop network settings and test in the application you actually use. A browser reading system settings does not mean a package manager or terminal tool will do the same. For applications that require separate settings, enter the local proxy type, address, and port in their network options. “Global mode” does not mean the operating system forcibly routes every process through the client.

Proxy environment variables in a terminal also have a limited scope: setting one for a terminal session does not automatically affect applications launched from the application menu. Adding one to the login environment may not affect processes that are already running. For the initial setup, avoid adding variables to multiple startup files. First verify the proxy in the target application, then decide whether to make it persistent. When reverting, remove it from the same source so an old variable does not keep pointing to a local port that is no longer listening after the client exits.

Check permissions, ports, and DNS

If you need TUN, follow the current build's permission prompts to set up its helper service or required capabilities. Service managers and security policies vary by distribution, so do not reuse commands from another platform. Check that the virtual interface is created, routes point to the expected interface, and DNS requests follow the intended path. If both the desktop network manager and the client try to change DNS, connections may work while name resolution fails intermittently. Switch back to a regular proxy, verify the basic connection, then restore traffic handling settings one at a time.

Use system tools to check whether a local port is occupied. The commands below only inspect listening sockets; they do not change network settings. Replace the port numbers with the values shown in the current interface. A listening socket alone does not prove that it belongs to the core you just started; check the process information and client logs as well. If no process name is shown, it may be a permissions issue, so do not assume the port is free.

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

If the subscription updates but an application cannot connect, first check the application's proxy source and proxy type. If the regular proxy works but TUN does not, focus on permissions, routing, and DNS. If the core is not listening at all, revisit the installation, configuration syntax, and file permissions. This sequence makes it easier to preserve the evidence than repeatedly changing distribution settings. If a security policy blocks execution or access, check the specific denial in the system logs rather than disabling the entire policy.

Test what happens when you exit as well: disable TUN, clear the system proxy, quit the client, and check whether desktop and application-specific proxy settings have been restored. Recheck the active interface after switching networks, waking a laptop from sleep, or connecting Ethernet. Boot-time and user-login environments are different; graphical clients usually need to start after the user session is available. Until you have a reliable baseline, avoid adding background startup or duplicate service instances, which can cause port conflicts and split configuration directories.

Set up V2Ray on Android

Choose v2rayNG or v2flyNG

Open the Android downloads and choose v2rayNG first; choose v2flyNG if you need an environment using the V2Fly core. These are separate apps, not two modes that switch the core in one installation. arm64 works on most newer devices; if you are unsure of the architecture, use the universal package. Before installing, allow the browser or file manager that will open the package to install apps. Grant this permission only to the app that needs it, then turn it off afterward if that fits your device's security practices.

If installation or an upgrade fails with a package conflict, an overwrite error, or a signature mismatch, stop retrying and check the identity and source of the installed app. Do not uninstall it immediately; doing so may also remove server entries and local settings. First export anything you need using the current app, then determine whether you have a different app installed, selected an incompatible package, or cannot upgrade directly from the existing version. Low storage can also cause installation failures and should be checked separately from architecture compatibility.

On first launch, review the default settings instead of importing a complete configuration from an unknown source. A full configuration may include custom DNS, routing, and local listening addresses that change how the app behaves. For a standard subscription, use the subscription option. To add a server manually, verify the protocol, transport, and TLS settings individually. v2flyNG is not a drop-in replacement for every Xray feature; support depends on the core in use, not the app's icon or name.

Subscription settings and connection authorization

In v2rayNG, open Subscription settings from the menu, add a subscription name and URL, save, then return to the main screen and update subscriptions. The Add button may appear in a different place between builds, but the order is the same: save the subscription entry before updating the server list. To import a single link, use the clipboard import option; to scan shared connection details, use the relevant QR code option. Do not mistake a subscription URL in a QR code for a single server, or repeatedly add a single-server link as a subscription.

After the update, tap a server entry, confirm it is selected, and start the connection. The system will ask for permission to establish a VPN connection the first time. This is Android's traffic-handling interface; it does not mean you need to install another VPN app. Check the status bar and app logs to confirm the service actually started. If another network tool is using the same interface, Android may switch between or stop one of the apps. For troubleshooting, run only this client to avoid two apps competing for traffic-handling permission.

v2flyNG follows the same import principles: distinguish subscriptions from individual configurations, then check the selected entry and core compatibility. A server appearing in the list does not mean the current core can use its transport settings. If a connection fails, note the first handshake-related error instead of repeatedly changing settings. If your connection details require a specific Xray feature, check the provider's settings and choose a compatible app rather than removing security fields just to make the client appear to start.

Per-app traffic handling, background operation, and DNS

Android primarily handles traffic through a VPN interface created by the app; this is different from the desktop “Set system proxy automatically” option, so there is no need to copy the desktop local proxy settings. To route only selected apps, choose which apps to include or bypass in the client's per-app settings, if supported. You will usually need to reconnect after saving. First check whether the list is an allowlist or a blocklist: selecting the same app can have opposite effects in each mode. Test with a single target app.

If the connection drops after the app runs in the background, check battery optimization, background activity limits, and the manufacturer's power-saving rules. Allow necessary background activity and notifications so the system can keep the connection service running, but do not grant extra permissions to every app just for troubleshooting. If it fails only when the screen is locked, check whether the background service is being stopped. If it fails while switching between Wi-Fi and mobile data, reconnect and check network change logs. These are different problems, not necessarily signs of an unreliable server.

Android Private DNS, the client's DNS settings, and a browser's encrypted DNS can all affect name resolution. If domains will not load, first restore one clear DNS path, then add custom settings one at a time. Do not enable special DNS settings in several places at once and use that to judge routing rules. Some manufacturers isolate cloned apps, work profiles, or private spaces. Make sure the target app and client are in the same environment, and select the correct app identity in per-app settings.

After stopping the connection, check the notification shade and verify that the network has recovered. If Always-on VPN or Block connections without VPN is enabled, network behavior after the client stops may differ from a normal exit; check these options in system network settings. On networks that require sign-in, complete authentication before connecting. Finally, test foreground use, background use, screen-locked use, and network switching separately. Keep one stable configuration before adding per-app rules so background restrictions are not mistaken for subscription or protocol errors.

Routing and traffic handling

Start by separating two different problems

Traffic handling determines whether a request reaches the client; routing determines which outbound it uses once it gets there. System proxy, application-specific proxy, and TUN belong to the traffic-handling layer. Domains, IPs, ports, and outbound tags belong to the routing layer. Switching routing to global mode cannot force an app that ignores the system proxy into the client. First check whether the target app's request appears in the logs. If it does not, troubleshoot the traffic path rather than adding more domain rules.

Routing rules are generally evaluated in order, and the first match selects an outbound. Put specific rules before broad ones. Ad blocking, direct access to the local network, direct access to selected domains, and proxying everything else can form a clear baseline, but every rule should have a specific purpose. Pay attention to how fields within a rule are combined. Do not put conditions in one rule object if you mean “match either the domain or the IP”; use separate rules for independent checks to make logs easier to interpret and future changes easier to maintain.

geosite provides domain categories, while geoip provides IP categories; both depend on the matching resource files and tags. Tag names are not arbitrary labels: typos or missing resources can prevent startup. Choosing built-in rules in the client's routing editor usually helps keep resource paths consistent. Before copying a configuration snippet, check that the required resource exists locally and that the client will not regenerate its configuration at startup and overwrite your changes.

Local inbounds and what the fields mean

The following is a complete V2Ray configuration that demonstrates local inbounds. It provides SOCKS and HTTP entry points on the loopback address, with direct connection as the default outbound. It helps explain listener and routing structure, but contains no remote proxy server and is not a substitute for a subscription. Clients usually generate their own runtime configuration, so do not overwrite the configuration currently in use with this example. For testing, use a separate configuration environment and make sure the example ports are not already in use.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    },
    {
      "tag": "http-in",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

listen sets the listening interface, port sets the local port, and tag names an inbound or outbound. A rule's outboundTag must refer to an existing outbound tag; using a nonexistent name does not create a proxy outbound. In the example above, requests that match no rule use the first outbound, which is direct. A client's “final rule” setting is usually converted into a specific configuration, so do not copy the interface label as if it were a core JSON field.

domainStrategy controls how routing handles domains and IP matching. AsIs keeps the domain for matching; IPIfNonMatch tries to resolve it for IP rules if no domain rule matches; IPOnDemand resolves it when an IP check is needed. This is not a standalone remote DNS switch, nor does it guarantee that every domain uses the same resolution path. Consider it alongside DNS settings, outbound behavior, and the client implementation.

Verify results with the smallest possible rule set

When adding a rule, choose a repeatable test target, note the expected outbound, and check the actual selection in the logs. Domain rules usually contain a hostname, not a full webpage path; distinguish subdomains, exact matches, and suffix matches. If an app connects directly by IP, uses encrypted DNS, or reuses a connection, the logs may not show the domain you expect. Check the actual request details instead of continually adding similar domains to a rule set that is both redundant and hard to explain.

A system proxy works well for apps that follow system settings; TUN can handle a broader range of traffic, but it does not determine the routing policy. After enabling it, prevent the core's own outbound traffic from looping back into the tunnel, and handle DNS and local network destinations correctly. Keep the client's default loop-prevention settings for your first test; do not casually change interface binding or route exclusions. If local printing, file sharing, or virtual machine networking stops working, check the path for private IP addresses before adding precise direct-routing rules.

Maintain routing rules separately from subscriptions. A subscription update may rebuild server entries, but it is not a general fix for routing errors. Updating routing resources does not update server settings. Keep a copy of the old rules for every change, test the target application and local network traffic, then check that the network recovers after exit. For core feature compatibility, see Xray vs. V2Fly core and check whether the fields are supported. Avoid repeatedly deleting and editing settings in the hope that they will work with an incompatible core.

Common configuration issues

Read logs by failure stage

First note what action failed, then record the error. A startup failure, subscription update failure, one application's connection problem, and a disconnect after sleep call for different troubleshooting steps. Open the log window, clear or mark old entries, reproduce the issue once, and look for the first error and its context. The final “startup failed” message is often only a summary; the real cause may be earlier in the log. For a more detailed breakdown, see Diagnosing core startup failures from logs.

If the logs show something like address already in use, first find out what is using the local port. Quit old clients and background instances, then check whether the listener has closed. If you need to change the port, update both the system proxy and any application-specific proxy settings. For a configuration parsing error, check JSON commas, brackets, field types, and whether the core recognizes the field. Valid JSON only means the syntax is correct; it does not mean the current core supports every field or that referenced files and tags exist.

If the logs report a missing resource file, check the rule file path, installation, and access permissions instead of deleting all routing rules. If they report an unknown protocol or unsupported transport, check the core against your connection details. Before switching cores, disable configuration that depends on specific features and confirm the new core supports the same protocol. Do not make “it starts” the only goal: removing TLS, authentication, or verification fields may change what the connection means. An error disappearing does not prove the settings are correct.

Empty subscriptions, timeouts, and certificate errors

If the list is empty after a subscription update, check the selected group, keyword filters, endpoint response, and subscription authorization in that order. A webpage or empty response is not the same as server data. Temporarily clear the filters and update a single group to find out whether fetching failed or display settings hid the entries. For multiple sources, use clearly named groups; see Subscription groups and server filtering. Do not use duplicate imports to compensate for unclear group organization.

A timeout means a step did not finish within the expected time; it does not by itself mean the server is down. First check whether the local port is listening, then whether the remote address resolves, and where the connection stops: connection establishment or protocol handshake. For connection refused, check the destination address, port, and service status. If the destination is a loopback address, confirm that the local core has started. Trying another server can help as a comparison, but keep the original error and settings so you have a baseline.

For a TLS certificate error, first check the system clock, server name, and security settings in your connection details. The certificate name may differ from the connection address, but only use that setup when the provider explicitly specifies it; do not guess. Do not make certificate verification bypass your default fix. If the subscription details are out of date, refresh them or ask the provider to confirm them. A network sign-in page, corporate proxy, or security software may also alter the certificate chain, so consider the network you're currently using.

Compare failures and know how to roll back

If a browser works but another app does not, first compare proxy sources: check for browser extensions, whether the target app uses the system proxy, and whether the proxy type and port match. If a regular proxy works but TUN does not, focus on permissions, the virtual interface, routing, and DNS. If a domain fails but an IP connection works, name resolution may be involved. But direct IP access can fail because of TLS name checks or virtual hosting, so a single test cannot rule out every other cause.

If one site fails while other services work, check the request's outbound, domain rules, and application cache. Existing connections may continue using the old route after a rule change, so establish a fresh connection before testing again. If needed, temporarily switch to a minimal rule set for comparison, but back up the original first. If the minimal set works, restore custom rules one at a time. If it still fails, check the remote connection details and traffic-handling path. Without a request in the logs, changing domain categories is usually troubleshooting the wrong layer.

For network-switching and background issues, recording what triggers them is more useful than noting that they “sometimes fail.” Specify whether the problem starts on screen lock, sleep, a Wi-Fi change, launching another tunnel app, or updating a subscription, then check the relevant logs. On Android, check whether the system stopped the service; on desktop, check the active network interface and any leftover proxy. A restart may temporarily clear the state, but if the problem recurs after the same action, test that action rather than relying on restarts as routine maintenance.

When reporting an issue, include the operating system, client name, selected core, steps to reproduce, exact error text, and comparison tests already performed. Do not include your full subscription or account details. Before sharing logs, check for server addresses, query parameters, and credentials, and remove sensitive information. To set up a basic connection again, return to the Quick Start Guide. To choose a package for another platform, visit the client downloads page. Keeping a baseline you can restore makes problems easier to isolate than repeatedly deleting all your settings.