V2Ray Setup Guide for All Platforms

Before You Start: Check Your Device, Configuration and Traffic Scope

Understand the client, core and connection configuration

Start by separating the three layers. v2rayN, v2rayNG and v2flyNG are graphical clients for viewing nodes, managing subscriptions and changing proxy modes. Xray and v2fly are cores that handle protocols, routing and connections. A subscription or share link provides server addresses, ports, credentials and transport settings. Installing a client does not give you access to a working server. Before you begin, prepare a valid configuration and confirm that your provider supports your device. This helps avoid mistaking missing connection details for an installation problem.

For desktop, start with v2rayN. The workflow is similar on Windows, macOS and Linux, but installation formats and permissions differ. On Android, v2rayNG with the Xray core is the usual choice; consider v2flyNG only if your configuration specifically requires the v2fly core. Protocol names alone do not determine compatibility: even VLESS setups can differ in transport, security and optional settings. Check the complete configuration against the selected client's core. Switching app icons will not resolve configuration incompatibilities.

Check your architecture, system environment and configuration source

Open your system's device information and note the operating system, processor architecture and current network connection. Desktop x64 and arm64 are not interchangeable, and an installer format does not determine processor architecture. Choose the right platform on the downloads page, then select the matching download. Check compatibility against the page and the installer's actual prompts; don't assume every system is supported based on an old article. Set the device clock to update automatically: an incorrect date can interfere with certificate validation and some protocol authentication.

Identify whether you have a subscription URL, a single-node share link or a complete configuration file. A subscription URL usually points to a collection of configurations retrieved over the network. A single-node link typically starts with a protocol prefix. A complete configuration file may define inbounds, outbounds and routing. Import each through its corresponding option. Keep an original copy, and watch for line breaks, trailing spaces or text truncated by a messaging app. Subscription URLs may contain account identifiers, so hide them in screenshots, logs and support requests.

Establish a basic connection before adding features

For the first setup, use one client, one selected node and one traffic-capture method. Start with the desktop system proxy or Android's VPN connection, and confirm that your browser can access the expected sites before adding split routing, app exclusions or TUN. Multiple proxy tools can compete for local ports, overwrite system settings or capture routes more than once. If a problem appears, return to this basic setup. It's easier to identify the cause than when changing subscriptions, cores and DNS settings all at once.

Know what the system proxy does and does not cover. It tells apps that follow system settings to use a local proxy, but not every app does so. Browser extensions, app-specific proxy options and command-line environments may use separate settings. TUN captures more traffic through a virtual network interface, but still depends on routing, DNS, app exclusions and system permissions. “Global” does not mean all data always uses the same exit under every circumstance. Check the client's actual rules and logs.

Finally, check your basic network connection without a proxy. If the device can't even open a sign-in page, troubleshoot Wi-Fi, network authentication or local DNS before configuring the client. Record any existing system proxy and custom DNS settings, especially on work or managed devices; don't overwrite existing policies. Test on the same network, using the same destination and mode. Change one setting at a time and record the result so you can roll back accurately instead of reinstalling and hoping for the best.

Windows: Install v2rayN and Configure the System Proxy

Choose the desktop or classic WPF edition

Open the Windows downloads section and look for v2rayN. The desktop edition uses a cross-platform interface, while the classic WPF edition keeps the familiar Windows look and workflow. Menus may differ, but subscriptions, active nodes, system proxy and routing are the same configuration layers. Choose an edition that meets the system requirements listed on the downloads page. Don't run both editions at once to test the same port. Pick one first, then match its shortcut to the correct working directory.

Run the installer, follow the system prompts and save configuration files somewhere your account can write to. If you downloaded a portable archive, extract it fully before launching the app; don't run it from the archive preview. If a runtime component is required, check the system prompt and downloads page instead of downloading it from an unfamiliar pop-up. If a security warning appears on first launch, verify the file source and warning details. Don't disable system-wide security protections.

Import a subscription and select the active node

In the main window, open subscription group management, add a group, enter a recognizable name and the full subscription URL, then save and update it. Adding the URL creates a subscription entry; an update is usually required to fetch its nodes. When the update succeeds, select a node in that group and use Set as active server, or the equivalent option. Highlighting a row may not switch the active node. Check the active indicator and confirm in the logs that the expected configuration loaded.

Start the core before enabling the system proxy. If you use automatic configuration, make sure you select the system proxy option provided by the client rather than entering a remote server address in Windows. The system proxy points to a local listening endpoint; the core handles the remote connection. Open Windows proxy settings to check that the address is a local loopback address and the port matches the client. Don't copy someone else's port number: use the value shown in your own client settings.

Test the system proxy and TUN with your apps

Open a test page in a browser that follows the system proxy and check for a new connection in the client. If the browser works but another app doesn't, check that app's own proxy settings, extensions or network options before changing nodes. If the app supports manual proxy settings, enter the HTTP or SOCKS endpoint actually provided by the client. Don't enter a SOCKS port as an HTTP port. Once tested, keep only one clear proxy configuration for the app.

Consider TUN when you need to capture traffic from apps that ignore the system proxy. Save the current configuration, grant the permissions required to manage the virtual network interface or routes as prompted, then enable the feature. For the first test, don't add a third-party VPN or manual routes. After TUN starts, look for the relevant interface or startup log. An enabled switch accompanied by a permission error does not mean traffic is being captured. For details, see the TUN mode guide.

Troubleshoot Windows startup and shutdown issues

If startup fails, check whether another instance is already using the listening port. Close duplicate instances and try again. If the problem persists, look in the logs for a specific port conflict, configuration parsing error or missing component. A protected installation directory or a configuration file locked by sync software can also prevent saves. Check directory permissions and file status instead of running everything as administrator indefinitely. Never delete subscription data you haven't backed up.

Before exiting normally, disable TUN, clear the system proxy set by this client, then close the app. After an unexpected shutdown, if no pages load, check whether Windows still points to a local proxy that is no longer running. Restore your previous settings and restart the client. Enable startup on login only after manual connections are stable, and check both the startup behavior and any elevation prompt. If problems appear after waking from sleep, restart traffic capture and recheck the network; you don't need to reimport the entire subscription.

macOS: Choose the Right Build and Check Network Services

Identify your chip and install the app

Open About This Mac and check whether your device has an Apple chip or an Intel processor. Then choose v2rayN from the macOS downloads section. Apple Silicon uses arm64; Intel uses x64. Don't guess based on the device's purchase year. The wrong architecture can prevent the app from running or add a compatibility layer, making troubleshooting harder. If the downloads page offers two builds, choose the one that matches your Mac's native architecture rather than installing both to test.

Open the disk image and follow the instructions to move the app into Applications, then launch it from there. Don't keep running it from the mounted image; upgrades, shortcuts and permission checks can become confusing. On first launch, follow the system prompt to confirm the app's source. If macOS blocks it, check the corresponding notice under Privacy & Security and follow the system's approved process after verifying the source. Don't use commands that disable system-wide security to bypass an unexplained block.

Import your details and check where the system proxy applies

In v2rayN, open subscription management, add a group and enter the full URL, then save and update it. Once nodes appear, set one as active before starting the proxy. If the configuration imports but the core won't start, check the logs for protocol, security-layer or transport errors. Successful import only means the client recognized the data; it doesn't guarantee that the selected core supports every option. When moving between devices, make sure you haven't imported a custom configuration intended for a different environment.

After enabling the system proxy, open network settings and check the network service currently in use. Wi-Fi, Ethernet and other services may each have separate proxy options; settings for one service may not apply after you switch connections. Check the local address, port and protocol, and don't enter a server domain as the local proxy address. If a work network uses an automatic proxy script, record its settings first so you can restore the existing connection path.

Once the browser test passes, test the apps you need. Some apps keep their own proxy settings; some terminal programs read only environment variables. An enabled system proxy doesn't prove every app is using it. For troubleshooting, temporarily disable browser proxy extensions and compare the default settings with the app's own settings for the same destination. If only one app has a problem, check its network options first rather than repeatedly changing system DNS.

Enable TUN and handle permissions and network changes

For broader traffic capture, use the TUN feature if the client provides it. Save your configuration, follow the permission prompts in the current interface, then check that the virtual interface and routes were created. Helper components and permission prompts vary by distribution and system environment; follow the client's current instructions. Don't copy interface names from an old article or manually delete system network interfaces when you're unsure what they do. If the network drops after enabling TUN, disable it first to restore your baseline.

When switching from Wi-Fi to Ethernet, a hotspot or a network that requires a sign-in page, first make sure the basic connection is established. The authentication page may need direct access, which can be disrupted by an existing proxy, DNS setting or route. Disable traffic capture, complete sign-in, then enable it again. If the core is still running but the connection stops after waking from sleep, check whether the network service changed and re-establish traffic capture. Update node details only if the subscription has actually expired or its parameters have changed.

Save your configuration and keep a clear exit procedure

Before upgrading the app, back up subscription groups and essential settings using a method supported by the client. Note your current routing and traffic capture modes. The app directory and user configuration directory serve different purposes; deleting the app does not necessarily remove its settings. When moving to a new device, reimport the original subscription first, then restore custom settings one at a time. Don't copy network paths, permission state or interface-specific parameters from an old device. Store backups somewhere you control, and don't share them publicly.

If you still can't connect after quitting the app, check whether the current network service still has a local proxy address and whether the corresponding local process is running. Restore the previous settings from your notes, then test the basic connection. If an enterprise network tool is also installed, follow device management requirements instead of changing managed policies yourself. Keep a clear startup and shutdown sequence: establish the network, start the core, then enable traffic capture; shut down in reverse order to make leftover settings easier to spot.

Linux: Choose a Package and Distinguish Desktop Proxy from TUN

Choose an installer for your distribution and architecture

Open the Linux downloads section and choose v2rayN. Check your distribution and processor architecture in system settings or device information, then select a package. deb is commonly used by Debian, Ubuntu and related distributions; rpm is used by distributions with the corresponding package management system. They are not interchangeable archive formats. Desktops commonly use x64, while some devices use arm64. The package format and architecture must both match. A file extension alone doesn't tell you whether a package will install.

Use your system's software installer to install the local package so the package manager can handle dependencies and keep installation records. If a dependency is missing, check which component is required and which system version you have, then confirm that your environment is supported. Don't force the installation by ignoring dependencies or replace system libraries just to run a client. Launch the app from the applications menu. If its desktop entry doesn't appear right away, sign in to the desktop session again and verify that installation completed.

Manage subscriptions and local proxy settings as a regular user

Run the client from your everyday account first. Import and update the subscription, then select an active node. Subscriptions and interface settings usually belong to the current user. Running the app with elevated privileges long-term can leave files that your regular account can't edit, causing later saves to fail. If settings won't persist, check the configuration directory's owner and write permissions rather than launching the app with higher privileges again. Back up configuration before migrating, then restore it using an import method supported by the client.

A Linux desktop proxy is not a universal switch for every process. Desktop environments may use different settings mechanisms, while browsers, software stores, terminals and background services may read system settings, environment variables or their own configuration. Start by testing a browser that clearly supports the system proxy, then check other apps individually. A terminal may need to be reopened after environment variables change; running services won't automatically inherit variables changed later in the desktop session.

Configure TUN permissions as guided by the client

Before enabling TUN, confirm that the client supports it in your Linux environment and read the permission requirements in its interface. Creating a virtual network device and changing routes usually require additional permissions, but that doesn't mean the graphical app should always run with elevated privileges. Prefer a helper service or authorization flow supported by the client. Don't copy permission commands from another distribution or grant the entire app directory excessive access just to dismiss a prompt.

After startup, check the logs to confirm that the virtual interface was created and routes were added, then test app traffic. Your system DNS manager, network management service and client DNS settings may all be involved. Identify which component receives queries and which provides the upstream resolver. If domain names fail but direct network connections work, check DNS-related errors first rather than assuming the server is unavailable. Record the original resolver settings before changing them, and make sure you can restore normal resolution after stopping the client.

Resolve conflicts with ports, desktop sessions and network managers

A local port conflict is a common cause of startup failure. If another user session, an old instance or a different proxy tool is already listening on the same port, the new instance may not be able to create its local endpoint. Close instances you no longer need. If you must change the port, update every app that points to it manually; otherwise, the browser may keep using the old endpoint. Check firewall rules only as needed. Local use usually does not require exposing the proxy listener to the entire LAN.

A graphical interface that won't open and a network connection that won't work are different problems. If the display service, desktop session or interface dependencies are failing, fix app startup first. If the core runs but traffic doesn't flow, check the configuration and network path. A headless remote system is not the same as a graphical desktop setup. This guide focuses on graphical clients; it doesn't require setting up a separate background proxy service for troubleshooting, which could leave two sets of routes with unclear ownership.

Before enabling startup at boot, verify the manual workflow after a regular login. Startup tasks, user services and system services run with different accounts and environments; a path that works in the desktop session may not work in the background. After updating the app, check that the startup entry still points to a valid location. On normal exit, disable TUN and restore the proxy. If the network fails after an unexpected exit, compare the current setup with your original network configuration and restore the baseline before restarting the client. Don't clear the entire firewall or system routing table.

Android: Install a Client and Manage VPN Traffic Capture

Choose v2rayNG or v2flyNG

Start from the Android downloads section. v2rayNG is the recommended choice for most users; it uses the Xray core. Consider v2flyNG only if you need the v2fly core. These are separate clients, so don't assume they share subscription, routing or app-exclusion settings. For most recent phones, check the arm64 download first. If the device is older or its architecture is unclear, check the universal build details. Use the device's supported architecture and the installation prompt to make the final choice; appearance alone isn't enough.

Before installing, allow the current download source to install apps. Grant only the permissions needed by the browser or file manager you're using, and disable source permission afterward if you no longer need it. If installation fails, the package can't be parsed or it conflicts with an installed app, check that the file matches the device and the installation source of the existing app. Don't immediately uninstall and reinstall; uninstalling may erase configuration. Save the subscription URL and essential settings before deciding whether to migrate or reinstall.

Import a subscription, select a node and allow the connection

Open the app's subscription group or subscription settings, add a name and URL, save, then return to the main screen and update it. When nodes appear, select one and start the connection. If you copied a single-node share link, use the appropriate import-from-clipboard option; don't treat a full subscription URL as a single node. A highlighted list item, a running service and the system VPN icon indicate different things. Check all three during testing.

On the first connection, Android usually displays a system VPN permission prompt. Confirm that it was opened by the client you're using, then allow the connection. This permission creates a local traffic-capture interface; it doesn't confirm that the subscription server is available. If the VPN icon appears but pages won't load, continue by checking the node, DNS and routing. Android's traffic capture is not the same as entering an HTTP proxy in a desktop browser, and you don't need to enter a remote node address in the Wi-Fi proxy settings.

Check app scope and background restrictions

Test with the default app scope first, then enable per-app proxying if needed. Distinguish between “proxy only selected apps” and “bypass proxy for selected apps”—they mean opposite things. Use the wording shown in the current interface. After adding or removing apps, reconnect as directed by the client. If the browser works but another app doesn't, check whether it is excluded or running in another user profile, then check routing and protocol settings. A working desktop setup doesn't guarantee identical settings on your phone.

In most everyday scenarios, only one active VPN connection can run in a user profile at a time. Another VPN, a filtering tool that uses a local VPN, or an enterprise networking app may replace the current connection, making the client appear to start and then stop. For troubleshooting, keep only one traffic-capture tool active and check the system status and client logs. On managed devices, follow your organization's policies instead of disabling management features or bypassing system restrictions to keep a connection running.

Disconnects after screen lock or switching apps are often caused by background restrictions. Check whether battery optimization is limiting the client and whether background data is allowed, then reproduce the issue after locking the screen. Don't disable power saving for the whole device; adjust only the app settings you need. Background operation can't guarantee an uninterrupted connection. Switching from Wi-Fi to mobile data may require reconnecting. Check actual access and new connection records to confirm recovery, not just the notification icon.

Handle network changes and always-on VPN settings

After switching between a hotspot, Wi-Fi and mobile data, first make sure the device itself can connect to the internet, then check the node. Some networks require web sign-in; temporarily stop traffic capture to sign in, then reconnect. If only mobile data fails, check mobile data permissions for the client and the affected app. If every network fails, check the subscription, device time and configuration parameters. Narrowing the problem down to one network is usually more useful than cycling through multiple nodes.

Before enabling always-on VPN or blocking connections without a VPN, understand the consequences: if the service stops, the device restarts or the subscription expires, system settings may restrict other network access. Enable these options only after a regular connection works reliably, and remember where to undo them. Before switching clients, stop the old service, back up your configuration and check what the new app's core supports. After migration, reconfigure app scope instead of relying on remembered rules that may not have been saved.

Subscription Management: Import, Update and Migrate Configurations

Identify your configuration and choose the right import option

First, identify what you have. A single-node share link typically starts with a protocol prefix such as vmess:// or vless:// and contains the details needed to connect to one server. A subscription URL retrieves a collection of configurations. A complete JSON configuration may describe inbounds, outbounds, DNS and routing. Use the matching import option for share links, subscription groups or custom configurations. File extensions and URL appearance are only clues; check the content format too.

A single-node link is useful for a quick test or a fixed configuration; if its parameters change, you'll usually need to import it again. A subscription manages a group of provider-maintained nodes and fetches updated content when refreshed. A QR code is just a way to encode text; after scanning, identify what kind of data it contains. A link that opens in a browser isn't necessarily a client-readable subscription. Login pages, error pages and account management pages aren't valid node lists.

Create a group and verify the update

Create a separate group for each source and name it by purpose or device so you can track it. After saving the URL, update it manually and check the result and whether nodes appear. If the client offers both proxied and direct updates, choose a path that actually works. Relying on a broken proxy to update a subscription when you don't yet have a working node creates a dead end. Switch update methods only when you've confirmed that the subscription requires a different, working network path; repeatedly pressing the button won't help.

After updating, verify the active node. Some clients try to keep your previous selection, but the active item may change or become unavailable if a node was removed, renamed or replaced. A node name is only a label, not reliable proof of server identity; check its group and connection details if names match. Set up automatic updates only after manual updates are reliable, and avoid excessively short intervals. Frequent refreshes won't fix an expired account, request limits or incompatible content, and can make errors harder to distinguish.

Troubleshoot empty lists, missing nodes and incompatible settings

If no nodes appear, first determine whether the download failed or the response couldn't be parsed. For download failures, check the full URL, network path, account status and system time. For parsing failures, check that the response is in a valid format and that it doesn't contain options unsupported by the current core. Don't paste a subscription URL into a public online tool to inspect it; it may grant access to your account. When asking for help, share only a redacted error summary with host details, account parameters and credentials removed, and mention the client and platform.

If only some nodes are missing, check whether the protocol, transport and security-layer combination is supported, and whether the client has filters enabled. The same protocol name doesn't mean another core can recognize every extended option. Don't delete fields such as TLS, REALITY, service names or paths just to make an import succeed; the client and server must agree on these parameters. For background, read share links vs. subscription URLs, then check the original data.

Back up before migrating and verify after updating

Before changing devices or reinstalling, back up subscription sources, manually added nodes, routing rules and app exclusions separately. Updating a subscription can restore nodes still provided by its source, but may not restore local notes, custom ordering or nodes removed by the provider. A complete configuration export may not work across platforms because local listeners, file paths, virtual interfaces and permissions differ. During migration, restore connection details first, general rules next and platform-specific settings last.

Don't rely on editing subscription-generated nodes as a long-term solution. The next update may overwrite your changes. If you need to modify one, duplicate it as a separate entry if the client allows it, and note why you changed it. That keeps local experiments separate from the source configuration. Check manually added nodes periodically too; the fact that they aren't automatically updated doesn't mean their server settings can never change.

After restoring your settings, run a minimal test with one node. Confirm that the core starts, traffic reaches the app and domain names resolve before restoring more groups and rules. Node notes or subscription expiry labels don't replace a connection test; a client that can read the list doesn't mean the account still allows connections. If the provider changed formats or core requirements, check the migration notes before updating client settings. Don't delete groups in bulk before backing them up, or you'll lose your baseline for troubleshooting.

Modes and Routing: Understand Traffic Entry Points and Rule Order

Separate traffic capture from routing modes

The system proxy and TUN determine how traffic enters the client. Global proxy, direct connection and rule-based routing determine where it goes afterward. These controls operate at different layers. Apps that ignore the system proxy may still connect directly, even when it's enabled; TUN can capture traffic while routing rules still send some connections direct. When troubleshooting, first check whether traffic entered the core, then see which outbound it matched. Don't assume that a “global” setting proves the app is being captured.

Start with the default rules to establish a baseline, then decide what needs to change. Global proxy can help rule out split-routing issues temporarily, but won't fix a bad server or DNS problem. Global direct is useful for testing the local network, but doesn't prove that all client background requests use the same settings. For long-term rule-based routing, know where the default outbound, LAN handling and app exclusions are configured. Interface labels vary; check the actual rules and logs.

Order rules from specific to general

Routing rules are commonly evaluated in order. Once an earlier rule selects an outbound, later rules of the same kind usually won't change that decision. Put specific domains, work networks and LAN rules before broader rules. Domain rules and IP rules are not equivalent: a domain may not have been resolved yet, or the client may see only an IP depending on the app and traffic capture method. Before troubleshooting, check what destination information the core actually received instead of inferring the match from the browser's address bar.

This Xray routing snippet illustrates rule order: send the example domain and its subdomains through a proxy, and route common private IP addresses directly. It isn't a complete client configuration; merge it into a configuration with matching outbound tags. proxy and direct must match the actual outbound tags. If a graphical client generates its configuration automatically, set up the same logic in its custom rules interface rather than overwriting a file that will be regenerated at startup.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "ip": [
          "10.0.0.0/8",
          "172.16.0.0/12",
          "192.168.0.0/16"
        ],
        "outboundTag": "direct"
      }
    ]
  }
}

domain:example.com matches the example domain and its subdomains; it doesn't mean any address containing that text. Private network ranges don't cover every special-use address or IPv6 case. AsIs doesn't force domain resolution just to apply an IP rule, so a domain destination may not match a later IP rule. This snippet expresses only two specific routing intents. Remaining traffic follows the complete configuration's default behavior, so don't import it as a complete split-routing setup.

Check rule resources, DNS and IPv6

When using geosite or geoip categories, the rule files must be present and compatible with the current core's format and category names. A missing category, a resource loading error and a network connection failure are different problems; check the startup logs first. Don't add large numbers of rules unless you understand their source and meaning. For a structured overview, see the routing and split-tunneling guide, then make a few clear changes for your own domains.

DNS controls how names are resolved; routing controls how connections are sent. They affect each other but are not interchangeable. An app may use its own encrypted DNS, or resolve a name to an IP before connecting. What the client can see varies, so domain rules may behave differently. With TUN enabled, check whether DNS queries follow the expected path and whether a usable outbound is available for remote resolution. Don't change every resolver at once; use the logs to find where the failure occurs.

Check IPv6 as a separate network path. Having an IPv6 address doesn't mean the current node, destination and traffic capture rules all support the same connection method. If a dual-stack network has problems, compare address-family results in a controlled test, but don't permanently disable IPv6 as a universal fix. Printers, file sharing and internal domains may also need direct access. Test these local services before adding broad rules that could disrupt your existing network.

After each change, test the same destination again and check which rule or outbound appears in the logs. More rules don't necessarily make routing more accurate; back up unclear old rules before cleaning them up. Once everything works, save the setup as your long-term configuration and record the default outbound and rollback steps. If an app bypasses the system proxy, fix the traffic entry point instead of adding more domain rules. Routing can't handle a connection that never reaches the core.

Configuration Troubleshooting: Trace the Connection One Layer at a Time

Classify the symptom before choosing what to check

Describe the problem in a reproducible way: the app won't start, a subscription update fails, the core won't launch, only domain lookups fail, only one app fails, or the connection drops after screen lock or a network change. Note the platform, traffic capture method, active node and most recent working change. Don't reduce all of these to “it doesn't work”; they occur at different layers. Turn off traffic capture to check the basic network, then reproduce the issue with one node and one app. That's the most reliable place to start.

If the app won't open, check installation, architecture, system dependencies and permissions first. If the interface works but the core fails, check configuration parsing and local ports. If the core is running but there are no app connection records, check the system proxy, app exclusions and TUN. If connections appear but fail, check destination resolution, the server and protocol settings. This order avoids changing routing before the program starts or mistaking an expired subscription for a permissions issue.

Read logs with enough context

Note when the error occurred, then check the surrounding log lines instead of looking only at the last word. A port conflict usually points to a local process issue. Authentication or handshake failures may involve credentials, time, transport or security-layer settings. Name resolution failures call for checking the DNS path. A timeout means an operation didn't complete within the allotted time; it doesn't identify which side failed. Compare the target, outbound and basic network results to narrow it down.

For more detail, temporarily change the log level in the client's settings. The following is a valid log object for an Xray configuration; it contains no server details and is not a complete connection configuration. Prefer the graphical client's settings. Direct edits to generated files may be lost after a restart. info can help monitor operation. If that isn't enough, briefly enable a more detailed level, then restore the previous setting when finished to avoid recording unnecessary connection details over time.

{
  "log": {
    "loglevel": "info"
  }
}

Before sharing logs, remove subscription URLs, identity parameters, server credentials and paths that could identify you. The error type, timestamps and essential destination details are usually enough to discuss a problem. Don't post a complete exported configuration publicly or let an unfamiliar tool read your subscription. For more troubleshooting answers, see the FAQ. Share details relevant to the layer that's failing instead of publishing screenshots of every setting.

Distinguish latency, throughput and real-world availability

A latency test is a diagnostic clue, not a guarantee that a connection will work. A TCP connection test mainly checks whether a port can be reached. A real proxy connection test also involves the proxy handshake and test destination, while a download speed test depends on throughput, congestion and concurrency. A low result for one metric and a page that won't load aren't contradictory; the test and app may use different paths. Compare the same node, network and destination, rather than treating results from different times and protocols as a measure of stability.

If only one destination fails, check whether others work, then investigate that destination's DNS, protocol and routing. If all destinations fail, check the active node and traffic entry point first. If just one app fails, check its settings; if only one network fails, check authentication, address family and connection restrictions. For more on test results, see latency tests vs. download speed tests. Repeating speed tests is no substitute for reading the error logs.

Roll back settings and confirm recovery

For a complex issue, undo recent changes in reverse order: disable newly added rules, restore default DNS and traffic capture settings, and only then consider reimporting connection details. After each rollback, test the same destination and record the result. Before resetting the client, back up subscriptions, manual nodes, routing and app scope. Reinstalling may not remove user settings or restore system network settings, so it isn't a reliable first troubleshooting step.

Keep a verified minimal configuration and recovery notes. On desktop, check that the system proxy can be cleared and TUN can be disabled cleanly. On Android, confirm that background operation, app scope and always-on settings behave as expected. Back up before upgrading, run a minimal test afterward, then restore complex rules. To repeat the full connection setup, return to the quick-start guide. To check installation options, visit the client downloads page. Keeping installation, configuration and troubleshooting separate makes each step easier to manage.