Complete Guide / Configuration & Troubleshooting

Complete V2Ray Client Guide

Start by choosing a client and verifying your first connection, then configure routing, TUN, and routine maintenance. Each chapter explains which layer a setting affects, how to check it, and how to roll it back.

To get connected quickly, follow the Quick Start Guide. For field details, platform differences, or help identifying where a problem occurs, consult the relevant chapter in this guide.

1. Core Concepts: Clients, Cores, and Connections

The interface saves settings; the core handles traffic

Start by separating the client from the core. v2rayN, v2rayNG, and v2flyNG are graphical clients for editing, importing, and starting or stopping configurations. The active configuration, subscription groups, and rule presets shown in the interface must ultimately be converted into a format the core can read. The core listens for local connections, evaluates rules, and establishes outbound connections. Seeing an entry in the list only means the interface can read it; the core may not have started, or it may have rejected a field while loading. If clicking Connect appears to do nothing, first check for a startup error, then determine whether to investigate the app's local entry point or the remote connection.

Project V is a useful starting point for understanding the V2Ray ecosystem. V2Fly continues V2Ray's community development, while Xray-core emerged from the same technical lineage and has since evolved independently. The two share some configuration concepts but are not guaranteed to support every field interchangeably. On desktop, start with v2rayN and select a core it offers based on the configuration you need. The two Android clients use different cores; their differences are covered in the next chapter. If the interface reports a successful import but startup fails because a transport or security field is unsupported, check which core the client actually launched. Don't infer its capabilities from the product name.

Protocols, transports, and connection security are different settings

VMess, VLESS, and Trojan identify outbound protocols, each with its own parameters and authentication method. A transport specifies how data reaches the other end, such as over a raw stream connection or WebSocket. TLS is one way to secure a connection; REALITY is a connection security mechanism available in Xray for specific deployments, not a field in the same category as VLESS. When reviewing a configuration, check the address and port, protocol, transport, and security method in turn. Don't assume two configurations are interchangeable just because they share a couple of familiar abbreviations.

The same domain can appear in several fields, but each has a different role. The server address identifies the remote endpoint. When TLS is enabled, the server name may be used during the handshake and to verify the certificate identity. The domain an app is trying to reach may be used for routing decisions. Putting a destination website's domain in the server address—or casually changing the security check when names don't match—won't fix an incorrect field. If a handshake fails, note the field type and error message, then compare each setting with a trusted configuration source. Don't replace a value just because it looks like a domain.

Start by tracing where traffic enters and where it goes

A local port opened by the client is an inbound connection. Traffic leaving the core may connect directly or be forwarded through a remote server; that's the outbound route. Proxy mode determines whether an app's requests can reach the client, while routing rules choose an outbound after they arrive. A browser may load a page without using the proxy, and a startup message in the core log doesn't prove that the browser used this inbound connection. Troubleshoot in four steps—app, entry point, matching rule, and outbound—and note the evidence for each. That way, you won't change a working remote configuration to fix an app that isn't using the proxy in the first place.

A subscription distributes a set of connection configurations. It isn't a protocol or proof that a remote server is reachable. Updating a subscription tells you whether the configurations could be fetched and imported; a connection test tells you whether the current app can use a configuration to complete a request. Track these results separately from the start: the group and time of each update, the configuration and app used for each test, and the client's first error message. These notes help distinguish an intermittent problem from a real change after a network switch or software update, and make it easier to restore a working setup when the cause is unclear.

2. Choose a Client: Platform, Architecture, and Core

On desktop, identify your OS and package type first

For desktop, v2rayN is the recommended starting point. Visit the Download Center and choose your operating system, then match the package to your device's processor architecture and package format. The operating system determines which download section to use, not which package in that section will work. For example, macOS packages differ for Apple Silicon and Intel; on Linux, having the right processor architecture doesn't mean you can use a package intended for a different package management system. If the system information is unclear, note its exact wording from Settings and check it. Don't rely only on the device's purchase year or the name shown in an app store.

PlatformClientHow to choose a package
Windowsv2rayNThe download section offers an x64 desktop edition and a classic WPF edition. Check your system type first, then choose an interface.
macOSv2rayNCheck the chip or processor under About This Mac, then choose Apple Silicon or Intel.
AndroidRecommended: v2rayNG; alternative: v2flyNGConfirm that the system supports arm64 before choosing this package. If you're unsure of the architecture, start with the general edition's notes.
Linuxv2rayNChoose x64 or arm64. The distribution's package management system determines whether to use deb or rpm.

The two Windows installers aren't different proxy protocols: the desktop edition uses a cross-platform interface, while the WPF edition uses the classic Windows interface. If you already have a preference, choose based on the menu layout. For a first install, use one edition to set up a subscription and test a connection; there's no need to open both just to compare them with a guide. Two instances may try to listen on the same local ports or change the system proxy independently. When the last one exits, it might clear settings the other instance is still using. If your system type doesn't clearly match an option in the Download Center, check the system requirements and download FAQs rather than using a package for another system as a substitute.

On Android, choose a core that supports your configuration

On Android, start by checking what core your existing configuration requires. v2rayNG uses the Xray core and is the recommended choice; v2flyNG uses the V2Fly core and is an alternative when you need to check a V2Fly configuration. If trusted configuration notes specify a field unique to one core, choose a client that supports it rather than treating a successful import as proof of compatibility. For common configurations, install one client and verify it first. If you need to compare clients, disconnect the existing VPN before testing the same destination with the other one. Otherwise, the system may have switched to the new VPN, making it look as if both clients are handling requests.

An Android device's processor may support 64-bit code even when the installed system doesn't provide a 64-bit environment to apps. If the system says a package isn't compatible, check the device requirements and the download source. If the package was transferred to your phone another way, make sure it is actually an Android installer. A general edition can reduce mistakes when choosing an architecture, but it won't change the core or make an unsupported system version compatible. If the system reports a conflict with an installed app, don't rush to uninstall it. First save a configuration you can import again, then check both installation sources.

Check compatibility in three stages

First, check whether the system can install the app. Second, check whether the core can load the configuration. Only then check whether the target app can connect. Each failure calls for a different response: for installation, revisit the system and architecture; for loading, check the fields and core; for app connectivity, check proxy mode, DNS, and routing. When moving to another device, transfer a subscription or individual configuration that can be fetched again rather than copying all app data. Traffic capture permissions, bound ports, and interface options may differ between devices. Starting with a minimal configuration is quicker than later figuring out which old settings caused conflicts.

You don't need a full specification sheet to document your choice. Record the device architecture, installer, client name, current core, and configuration source. You can also note why you didn't choose the alternative, such as “needs to load a configuration with an Xray-specific field.” If someone else's menu path looks different, use these notes to compare setups. If only the interface labels differ, look for the same feature under another name. To test whether a problem occurs only in a particular client, keep the network, destination, and connection configuration the same so the client is the only variable.

3. Installation: Permissions and First Launch

After installing on desktop, open the interface first

On Windows, run the installer for the option you selected in the Download Center and follow the system prompts. Then launch the corresponding v2rayN from the Start menu. You don't need to run every startup as an administrator just because you might enable TUN later. First, sign in with your usual account and confirm the window, menus, and settings work. Grant extra permissions only when a specific feature requests them. If a required runtime component is missing, note its full name and the installer you used, then check the download instructions. Don't replace it with a similarly named file from an untrusted source, and don't mistake an app launch failure for a subscription problem.

On macOS, use the disk image that matches your chip. Open it, follow the installer instructions to move the app into the Applications folder, then launch it from there. Don't use the mounted image as a permanent place to run the app. If the system blocks startup, read the message carefully to distinguish an architecture issue from a source or management policy issue, then check the download option and device requirements. On managed devices, follow the organization's policy rather than lowering system-wide protections for a single install. After installation, make sure you're opening the copy in Applications. This avoids launching an old copy from the disk image after an update and wondering why your configuration wasn't saved.

On Linux, open the deb or rpm using your distribution's graphical software installer, and check the architecture and dependencies it reports. If the system reports missing dependencies, first confirm that the package matches your distribution and architecture, then use the distribution's own software sources to resolve them. Once installed, launch v2rayN from the desktop app list. If the machine is used only through a remote terminal and has no desktop session for graphical apps, the graphical setup steps in this guide won't apply. Don't keep installing different package formats in search of a window, and don't make system directories writable by everyone just to get the app running.

Handle Android install permission separately from VPN authorization

When you open a trusted installer from a browser or file manager, the system may ask you to allow app installs from that source. Grant permission only to the app that actually opened the installer, then revoke it in system settings once installation is complete. Launching a proxy client for the first time and starting a VPN are separate steps: you can check the interface, subscription options, and saved settings before authorizing the system VPN. Without that permission, imported entries may still appear in the app, but the target app's traffic won't enter the VPN. If your device is managed by your organization, first confirm that the connection is allowed to replace the managed one. Don't remove the management policy yourself.

After a first install, don't rush to restore every setting from an old device. Turn off auto-connect and other clients that may change the network entry point, then launch the new app with its defaults. Open the settings page, exit, and reopen it to confirm that your account can save settings normally. On desktop, you can also note the local listener settings shown in the interface; there's no need to expose the ports to your local network. If the settings revert after restarting, check whether you opened another copy of the app, signed in with a different account, or encountered a data directory write failure. Since no subscription has been added yet, there are fewer possible causes to investigate.

Record a baseline for the first launch

A baseline isn't a speed test; it's a state you can observe consistently on the current device. First, use your usual network setup to open an everyday webpage and note that the client isn't capturing traffic yet. After closing the window, check whether the system proxy or VPN status remains unchanged. If a manual proxy or always-on VPN was already enabled, record its settings so you can restore them later. Then prepare a configuration from a source you trust for the next chapter. This gives you a before-and-after comparison if problems arise after import. If the network was already failing before the import, fix basic connectivity first instead of adding more variables.

4. Importing Subscriptions: Groups, Updates, and Activation

Distinguish subscription URLs from individual configurations

A subscription URL usually fetches a set of configurations, and the entries in the group may change when refreshed. An individual share link or QR code usually imports just one connection configuration and isn't refreshed through a group. Don't send a URL to an online conversion tool just because it looks like a regular webpage. A full URL may contain sensitive account information, and a QR code may include server addresses and identity fields. Confirm the source and format instructions first, then use the corresponding import option in the client. Don't paste the full URL into a public search box or chat group to identify its format.

In v2rayN, open Subscription Group Settings from the Subscription Group menu. Create a group, enter an easy-to-recognize alias and the “Optional address (URL),” then save. Return to the main window, select the group, and update the current subscription. On the first run, update just this group so it's easy to see where the new entries appear. Saving stores the URL; it doesn't fetch anything. Updating retrieves and attempts to parse the data. If the group already contains manually edited entries, save important configurations separately so a refresh doesn't overwrite or remove your local changes.

In v2rayNG or v2flyNG, open subscription group management from the sidebar or menu, create a group, and save its note and URL. Then return to the configuration list and update the subscription; exact menu names vary by interface. For an individual share link, use the add menu's clipboard import or QR scanner, then check the displayed protocol and group before enabling it. If the clipboard contains multiple lines, recopy the complete link from its source rather than extracting it from a chat history. Import one source at a time so duplicate aliases don't make it hard to tell which entry is selected.

When an update fails, separate fetching from parsing

If an update doesn't retrieve data, check whether the URL has expired, characters were missed when copying, the current network can make the request, and the device clock is reasonably accurate. If content was received but no entries appear, check whether the response is configuration data or an ordinary webpage such as a sign-in or error page, then check the format and core compatibility. Don't post the response body publicly. If the log shows a timeout, also check how the client is configured to fetch updates: direct fetching and fetching through the current proxy use different paths, and the latter requires an existing working connection. Repeatedly trying to update through an old connection that already fails won't fix it.

Once entries appear, choose one whose name and source you recognize. On desktop, set it as the active configuration. On Android, tap the entry, start the connection, and grant permission when prompted. Check the logs for field parsing errors or port conflicts, then test the connection using the same ordinary destination. Keep a known-working configuration as a comparison if needed. A successful subscription update doesn't guarantee every entry will work; a remote endpoint may be inactive or its security settings may not match. Test another trusted configuration from the same group before deciding whether to revisit the subscription as a whole or just note one failing entry.

Enable automatic updates after the first successful connection

Update manually and connect using one entry before deciding whether to enable automatic updates. In v2rayN's group settings, confirm that updates are enabled for the group and set an interval, in minutes, that reflects how often the source actually changes. New entries won't automatically switch the active configuration the way you expect, so check the active selection after each refresh. Devices using the same URL may update at different times and have different active selections. If the URL changes or the update process fails, see the subscription update troubleshooting notes and record whether the failure occurred during fetching, parsing, or selection.

5. Proxy Modes: Entry Points and Connection Tests

Start with system proxy on desktop

In v2rayN, select an active configuration, confirm that the core has started, then open the system proxy options and choose “Automatically configure system proxy.” This points the system proxy to the client's local entry point, making it a good starting point for testing in a browser that follows system proxy settings. If the browser has an extension that controls its proxy independently, check whether it overrides the system setting. Apps with their own proxy settings need to be checked separately. System proxy doesn't reroute traffic from every program, and it doesn't guarantee that every request goes out through the remote server. Routing rules still determine the outbound after traffic enters the core.

OptionWhat it doesWhat to check
Clear system proxyRemove system proxy settingsRestore any previous manual proxy settings from your notes; this option doesn't manage proxy settings inside apps.
Automatically configure system proxyPoint the system proxy to the client's local entry pointThe address and port in the system settings should match the active listener.
Don't change system proxyLeave system proxy settings unchangedA previously configured proxy may remain active; don't assume this option clears it.

If you only want a tool with manual proxy support to use the client, there's no need to change system-wide settings. Check the current local listener type and port in the client, then enter the matching type and your local loopback address in the tool's proxy settings. Don't enter the remote server's port in a local proxy field, or use a local HTTP endpoint as a SOCKS endpoint. Being able to enter a port number doesn't mean both sides use the same protocol. When you're done testing, remove the proxy settings from the tool before closing the client so it doesn't keep trying to reach a local address that is no longer listening.

Check VPN status before connecting on Android

On Android, the usual process is to select a configuration and tap Connect. The first time, the system asks you to authorize a VPN connection. Confirming the dialog only allows the system traffic capture tunnel to be created; it doesn't mean the remote handshake succeeded. If another VPN or work profile is already active, check the system's connection status and management requirements. For a straightforward test, use one client at a time. If the interface offers per-app proxying, the failing app may not be included. First test with the same browser, then check whether the target app is on an exclusion list.

Use one destination to check all three parts of the path

Keep the network and destination the same, then check three things in order: whether the client process is listening normally, whether the log shows a connection at the time the app makes a request, and whether the app gets the expected result. Reload the page to make a fresh request rather than treating a cached browser view as proof of connectivity. If the page loads but no request appears in the logs, the app may not be using this entry point. If the log shows an inbound request followed by an outbound timeout, revisit the rules and connection. Success on one website doesn't prove that every app and transport is working.

If the browser works but an update tool doesn't, first check whether the tool supports the system proxy, has its own proxy settings, or uses traffic that isn't captured by the current mode. If the system shows a local proxy configured but the core reports a port conflict, close similar clients or identify the process using the port before deciding whether to change it. After changing the port, check apps with manual settings too: the system proxy may point to the new port while an individual tool still uses the old one. Change only one entry point at a time so you can identify what caused the result. Don't change the node, routing, and port all at once.

Before ending a test, record the working state and restore the entry point. If the desktop was using a direct connection beforehand, clear the system proxy written for this test and confirm that ordinary pages still load after closing the app. If you had a work or personal manual proxy, restore it from your setup notes; clearing the proxy isn't the same as restoring its previous value. On Android, stop the app's connection and check the system VPN status, especially any always-on setting or option that blocks connections outside the VPN. If the whole device loses connectivity after stopping, check this layer before importing the configuration again. Verifying the entry point independently makes it easier to test routing in the next chapter.

6. Routing: Rules, Order, and DNS

Routing selects an outbound for requests that have already entered the client

Keep a verified routing preset and make a copy for experiments. A preset name helps you choose one, but doesn't replace checking its rules; the same “bypass” label can refer to different rule sets in different configurations. To evaluate a request, first check whether the app gives the entry point a domain or an IP address, then check the rule conditions and order, and finally check the outbound tag. If a rule matches domains but the app provides an IP, first check whether the core can recover the original destination at the current entry point. Don't try to compensate by adding a handful of similar domains at random.

A rule can match conditions such as domains or address ranges; some combinations require every condition to match. Rules are evaluated in order. A broad rule placed before a more specific one may prevent later exceptions from ever being used. Put more specific rules before broad ones and define the default outbound separately. After adding a site, test it, a destination that should use a different outbound, and an ordinary destination not listed in any rule. Testing only the new site won't reveal whether the change also altered the default path.

Core JSON example: direct connections to private networks and a default outbound

The following top-level routing snippet can be added to a custom Xray or V2Fly configuration; it is not a complete, ready-to-run configuration. The existing configuration must already define a direct outbound tagged direct and a proxy outbound tagged proxy, and retain its existing inbounds. If your tags differ, use the actual tags. When using a graphical client's rule editor, enter the conditions and outbound destination to match the snippet; don't paste the entire JSON into a domain field. Test it in a copy before applying it to a configuration you use regularly.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

This example sends IP requests that match the specified private ranges directly. The final rule matches all other TCP and UDP traffic that reaches routing. One easy-to-miss detail: IPIfNonMatch attempts to resolve a domain for IP matching only when no rule has matched. A valid broad fallback rule may match before that happens. So this example doesn't mean that every domain resolving to a private IP is guaranteed to connect directly. If you already know an internal domain, add a specific rule for it before the fallback. If you need to match an address based on a domain's resolved IP, consider the extra lookups and resolution paths introduced by IPOnDemand.

Check DNS queries separately from the final connection

Routing needs to identify the destination, but DNS queries also have their own path to a resolver. Routing a website's traffic through a proxy doesn't mean its DNS requests take the same route. The browser's encrypted DNS, the system resolver, and the client's built-in DNS may all be involved. Before making changes, note which is actually enabled, then choose which queries the core should handle. Test one direct destination and one proxied destination, and record the destination name, matching rule, and outbound in the logs. If needed, follow the steps in DNS routing and leak prevention to check the resolution path.

If only local network services stop working after a rule change, first test a known-good local IP address, then try the original domain. Different results often point to DNS resolution or domain matching that needs separate attention. If every destination fails, restore the backed-up preset and reload it to confirm you can recover the baseline. Then check for a reference to a nonexistent outbound tag or a rule that overrides an existing required exception. Instead of writing dozens of rules at once, add one type of condition at a time, test a set of results, and keep a record of the order. That checklist will help you spot behavior changes after a client update.

7. TUN Mode: Traffic Capture and Rollback

First determine whether the entry point is really the problem

TUN receives traffic matching system routes through a virtual network interface or a similar system mechanism. This means desktop apps don't need to understand system proxy settings. It's a useful next step when the same configuration works through system proxy but the target app doesn't use that entry point. If the configuration already fails to complete a handshake in a regular browser, or the core won't start, enabling TUN won't fix the remote settings. First write down which app you want TUN to capture and what should change compared with the current mode. A wider capture range doesn't necessarily mean greater reliability.

Capturing more traffic doesn't mean it will all use the same outbound. System routes, the client's TUN settings, local network exclusions, and an app's own DNS behavior can all affect the result. On desktop, you may need to enable a component and grant system permissions. Android usually uses the system VPN tunnel; don't copy desktop interface options directly onto a phone. If you have a special network setup, such as required access to a local network share or another virtual interface on the machine, prepare a rollback path first. If a remote session depends on the current network, don't switch capture modes without a way to recover locally if the connection drops.

Start v2rayN TUN from a clean baseline

First, confirm that a system proxy connection works on desktop, and note the original system proxy state, current routing, and active configuration. Then stop system proxy capture, keep the same active configuration, and make sure no other proxy client is changing system routes. Find the TUN toggle in v2rayN and grant any required permissions when prompted. If the option isn't available or startup fails, check the log for the component and error. Don't copy settings from a screenshot of a different operating system. For the initial test, check TUN alone—don't also add remote DNS or rewrite routing rules.

Once TUN is enabled, test three types of destinations in order: an ordinary webpage, an app that didn't use the system proxy before, and a local network resource that should remain direct. Start a fresh request for each test and check whether the logs show an inbound request or rule match when the app tries to connect. If only the ordinary webpage works, the original problem remains. If the app works but local resources disappear, check local network routes and exclusions. If everything works but the whole device behaves strangely after TUN is disabled, check whether the system's default route, original proxy, and DNS settings were restored. Note what's left behind rather than treating repeated toggling as a permanent fix.

Separate DNS, virtual IPs, and transport failures

Under TUN, DNS requests may take a different path. First compare whether a known internal IP is reachable and whether its corresponding local hostname resolves. If the IP is reachable but the name isn't, check the resolver selection and scope rather than reinstalling the client. With FakeDNS enabled, the returned address may be a virtual IP that the core mapped to a domain. For routing rules to use the recovered destination, later connections must return through an entry point that can restore that mapping. Read FakeDNS: how it works and when to use it to learn more; there's no need to enable it before establishing a baseline.

An app may load webpages but fail on voice or real-time connections because those use different traffic types. On the same network, turn TUN off for comparison and make sure the issue isn't inherent to the target app. Then check whether the current outbound and routing support the transport it uses. A working webpage doesn't prove that every type of traffic can get through. Conversely, if all requests fail immediately after enabling TUN, turn it off, restore the original system proxy state, and verify the baseline first. If you run a second test, investigate only one branch—such as permissions or a routing conflict—until you can identify which setting changed the result.

8. Maintenance: Updates, Backups, and Checks

Update subscriptions and software separately

Subscription updates change connection entries; client or core updates can change configuration parsing, the interface, and runtime behavior. If both updates are due on the same day, do one, verify it, then do the other. Review subscriptions as often as their source changes; there's no need to set a very short auto-update interval. After updating a group, check that the active configuration is still selected and look for duplicate names, then test a fixed destination. If a previously working setup fails after an update, compare it with a configuration you saved separately. That's easier than deleting and reimporting everything, and can help distinguish an entry change from a temporary network problem.

Before upgrading the client, note the installer you used and the current core. Save subscription groups, commonly used routes, local ports, DNS choices, and traffic capture preferences. If the upgrade notes mention configuration migration, first confirm that the backup can be opened in a suitable environment. After upgrading, don't change the core or routes yet. Use the same traffic capture mode as before, then check an ordinary destination and a local resource. If the new interface changes a default, record the actual option instead of relying on old screenshots. If you need to roll back, preserve any necessary records generated by the new version and restore from a pre-upgrade backup where possible. Don't feed migrated data directly to an older version.

Choose a backup method based on what you need to restore

A subscription URL is useful for rebuilding a frequently changing list. An individual export preserves a connection you know works, while a client backup can move groups and some preferences between similar devices. They don't contain the same things: a subscription URL doesn't save manual routing rules, an individual share usually doesn't include global settings, and a backup may not include system permissions or other system-level state. Before switching devices, read the guide to syncing configurations across devices and save each item you need. A QR code isn't a snapshot of the device's entire network setup.

Know where your backups are stored, how to open them, and who can access them. Configuration files may contain account identifiers and full subscription URLs. Don't put them in a publicly shared location or upload an entire archive in a public support request. When migrating, use the client's own import and export features where possible. After importing, restore only the groups and rules you need, then set local ports, device permissions, and traffic capture one at a time. Leave the old device's configuration untouched until the new device passes a full test. If entries import but saved routes aren't recognized, rebuilding a few necessary rules manually makes it easier to identify differences than overwriting the entire configuration.

Keep only useful details in troubleshooting notes

For intermittent problems, record the time, current network, your own alias for the active configuration, whether TUN is on, and which app failed. Then capture the first error in that time window. If the failure starts only after waking the device, note “worked before sleep, failed after wake” and check whether the network changed or the local listener recovered. If only one network is affected, retest on a network that works before declaring the subscription invalid. When asking for help, include the error category and necessary context, but remove full URLs, QR codes, identity fields, and identifiable browsing history.

Schedule a short check for devices you use regularly: confirm the configuration loads, ordinary destinations use the expected outbound, local resources remain accessible, and traffic capture can be turned off to restore the original network. Before sharing a computer's proxy with other devices, confirm that you need to do so and distinguish a loopback listener from one exposed to the local network. Don't expose it to untrusted networks. See v2rayN local network proxy sharing for specific checks. After stopping sharing, confirm the listener is no longer exposed. If you don't rely on this feature, leave it disabled to reduce the number of entry points to consider when troubleshooting ports.

9. Advanced Workflow: Controlled Tests and Troubleshooting

Use comparisons instead of toggling settings at random

Start advanced troubleshooting with a reproducible problem. Write down the baseline—“this device, this network, this entry point, this destination”—then change just one variable: client, core, rule, DNS, or traffic capture mode. For example, if a browser works but a tool doesn't, change only the entry point. Don't change routing and subscriptions at the same time. If both entry points fail, keep the app the same and test another active configuration. If you can't reproduce the failure, don't credit the last toggle you tried for one successful result. Record the same observation before and after each change so you can decide whether to proceed or roll back.

Describe a problem as “expected, actual, evidence, next step.” For example, you expect an internal tool to access local resources directly, but it times out with TUN enabled. The evidence is that the local IP is reachable but the domain request fails, so the next step is to check which resolver handles that domain. In another case, the client may never receive the tool's request; then check the entry point and capture scope before analyzing routing rules. Don't treat missing logs as proof that something didn't happen: the log level or coverage may be insufficient. Increase visibility briefly if needed, then restore your normal settings after the test.

Use a local baseline to understand startup and connection errors

On desktop, if the client fails to bind, first check the local listener type in its settings, then see whether the corresponding port is actually in use. On Windows, run the read-only command below in PowerShell to list local TCP listening addresses, ports, and process IDs. Match a process ID in Task Manager's Details tab to confirm whether it belongs to the current client or another program. The command doesn't verify the proxy protocol or test remote connectivity, so it can't tell you whether a subscription is good. When checking the bind address, remember that a local loopback address isn't the same as an address exposed on all interfaces. The latter should be reviewed against any existing sharing setup.

Get-NetTCPConnection -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

If the listener is working but the core reports a timeout connecting externally, distinguish between a destination that can't be resolved, a connection that never gets established, and a failure after the handshake begins. An unrecognized field usually causes a loading error; a certificate name mismatch occurs during a security handshake; an application error returned by the remote server is a later stage. Similar-looking log messages can mean different things, so check when they occur. Don't hide a name mismatch by disabling security checks. If the problem occurs only on one network, test the same configuration on a known-working network. If multiple configurations fail at the same stage, check local sharing and network conditions.

Plan your next practice exercises

For the first exercise, change just one domain rule: add a test destination that should connect directly to a backed-up copy of your routing configuration. Check where it and another ordinary destination go, then remove the new rule and test again. In the second exercise, investigate DNS: keep the same routing rule and compare name lookups and outbound results for a direct destination and a proxied one. In the third, test traffic capture: use an entry point the same app is known to support, then compare system proxy or TUN, keeping the setup as small as possible to reproduce. Write down the expected result and rollback steps before each test. If you can't explain the previous result yet, don't bury the problem under changes at another layer.

If your everyday setup uses only subscriptions, system proxy, and a few routing rules, understanding those three is enough. Explore TUN if you need to handle apps that ignore proxy settings. Review core differences, fields, and outbound tags when migrating or using a custom core configuration. For installation, architecture, or device requirements, return to the Download Center and download FAQs. To rebuild a basic connection from scratch, follow the Quick Start Guide. After troubleshooting, keep the last working state and repeatable verification steps. That's more useful than enabling every advanced option.