V2Ray Setup Guide
for All Platforms

Before You Begin: Setup and Scope

Understand the Client, Core, and Service Configuration

v2rayN is a desktop GUI client that manages subscriptions, generates configuration, and starts the core; v2rayNG and v2flyNG are for Android. The core handles connections, protocols, and routing. Project V is the starting point of the related open-source ecosystem, while V2Fly and Xray represent separate core development paths. Installing a client does not provide a usable service configuration. You still need an authorized subscription URL or an individual share link.

For desktop, start with v2rayN. On Android, v2rayNG is the usual starting point; consider v2flyNG when you need compatibility with V2Fly configurations. Choose based on whether the current core supports the protocols, transports, and security settings your configuration requires—not on the client name or feature count. For example, REALITY requires compatible support; changing the core name alone does not make a configuration compatible. See Xray vs. V2Fly: Choosing a Core for details.

Check Your System and Network Before Downloading

Go to Download Clients, choose your operating system, then select the processor architecture and package type. Check the system architecture and application architecture separately: being able to run an app through a compatibility layer does not mean it is the best package for your device. Check your processor in desktop system information or your Android device specifications. If you cannot confirm the architecture, choose a universal package offered on the download page. Do not infer architecture from a device's appearance or purchase date.

Before you begin, note the status of existing proxies, VPNs, virtual network adapters, and security software. With multiple network-routing tools enabled, it can be difficult to tell where traffic is going. Close other proxy clients, keep the network in its original state, confirm regular internet access, and let the system sync its time automatically. Encrypted connections rely on an accurate clock; a time mismatch can cause certificate validation errors. Do not hide these errors by disabling validation.

Organize Subscriptions and Backups

A subscription URL is an entry point for retrieving configurations; a share link describes a single configuration. Do not use one in place of the other. Subscriptions are often HTTPS URLs that return an encoded set of configurations, while share links use protocol-specific prefixes. Clients usually provide separate import options. Preserve query parameters when copying a URL, check for leading or trailing spaces and line breaks, and do not use a browser login page URL as a subscription. See Subscription URLs and Share Link Formats for details.

Before making major routing, DNS, or core changes, use the client's export or backup feature to save the current setup. Configuration may contain subscription parameters, user IDs, and service addresses; store backups somewhere you control. When asking for help, share only the error type, time, and necessary configuration structure, with identifying fields removed. Never post a full subscription URL in a public discussion or paste credentials into an online conversion tool.

Use a Troubleshooting Sequence You Can Roll Back

For initial setup, proceed in this order: install, import, select a configuration, start the core, enable a traffic entry point, then test access. Change one category of settings at a time and check the result before moving on. Start with the system proxy to verify basic connectivity before considering TUN; test with default routing before adding custom rules. This gives every change a clear starting point and lets you return to the last working state instead of guessing at several parameters at once.

Local port numbers below illustrate how settings relate; they are not fixed client defaults. Check the current settings page for the actual listening port before entering it in an app. A subscription does not determine every local setting: check the system proxy toggle, permissions, routing, and DNS separately. Follow the requirements for your network and device, and configure only in an environment where you are authorized to do so.

Windows: Install v2rayN and Import a Subscription

Choose the Desktop or Classic WPF Edition

Choose v2rayN from the Windows downloads. The desktop edition uses a cross-platform interface, while the classic WPF edition follows the traditional Windows UI. This is a choice of interface and app organization, not between two service protocols. For a first install, choose one. If migrating, back up your configuration first, then check the new interface's import options, listening port, and proxy mode. Avoid having both editions manage the system proxy at the same time.

During installation, choose a location you can write to and follow the prompts. If you use the portable archive, keep the entire folder intact instead of moving only the main executable to your desktop. The client needs its companion files and configuration directory. If a core is missing or security software quarantines a file, the interface may open while connections fail to start. If prompted for a runtime, read which component is required and choose one that matches your system and architecture; avoid repeatedly installing incompatible components.

Add a Subscription Group and Update It

Open subscription group settings in v2rayN, add a group, enter a recognizable name, paste the complete subscription URL, make sure the group is enabled, and save. Then update the subscription. If you do not yet have a working proxy, try updating without a proxy first. If you already have a working configuration and your network cannot reach the subscription provider directly, try updating through the proxy. After a successful update, check that the group contains configurations rather than remaining empty.

The automatic update interval controls how often the subscription is fetched; it does not keep a connection alive or change the service's validity period. Updating too often may trigger request limits. Filters affect what appears in the list, so leave them empty on the first import and add them only after confirming that the full contents appear. If an update reports success but the list is empty, check the selected group and filters, then confirm the provider returned subscription data rather than a login page.

Select a Configuration and Set Up the System Proxy

Select the configuration you want to use, make it active, and confirm that the core starts normally. Then choose Set System Proxy from the system proxy menu. The proxy port must match the client's local listening port. If another tool previously changed the system proxy, clear its old settings before letting v2rayN set them again. Browsers usually honor the system proxy, but games, command-line tools, and some desktop apps may not—so browser access alone does not prove that all programs are using the proxy.

Routing mode and system proxy are separate layers. The system proxy determines whether an app sends requests to the client; routing determines whether the client sends those requests direct or through the proxy. For a first setup, choose a routing mode that bypasses the LAN so local device traffic is not sent to a remote server. Adjust it later to suit your needs. To test a single app, enter the local address and actual port in an app that supports manual proxy settings; you do not need to enable system-wide routing right away.

Permissions, Sleep, and Restoring Connectivity

A regular system proxy usually does not require administrator privileges. TUN changes virtual network adapters and routes, so grant only the permissions requested by the current client. If LAN access breaks after enabling it, check the LAN bypass rules and routing table instead of turning off the firewall. If security software blocks the core, review its event log and the file location, then allow only what is necessary once you understand the cause. Do not whitelist everything.

After waking from sleep or switching between wired and wireless networks, the network interface, gateway, or DNS environment may have changed. Disable TUN and re-enable it; if that does not help, quit and reopen the client. If an unexpected exit leaves your browser offline, check Windows proxy settings for a stale manual proxy. Remove any unreachable local address and test the original connection. Restart the client after connectivity returns so a leftover proxy is not mistaken for a service failure.

Finish with two checks: visit a destination that requires the proxy to confirm the proxy route works, then access a LAN device or a destination expected to connect directly to check that routing has not disrupted local traffic. Review logs from the same time period to distinguish core startup, DNS resolution, and connection errors. A speed test is only an additional check, not a substitute for testing a real app. If the browser works but a specific program does not, first check whether that program supports proxies, then see the TUN section of this guide.

macOS: Choose the Right Chip Package and Set Network Permissions

Check Your Chip and Install Location

Check the chip type in About This Mac, then choose v2rayN from the macOS downloads. Use the package for the matching Apple Silicon architecture or the x64 package for Intel. Even if compatibility technology can run an app built for another architecture, prefer the native package to reduce variables in core startup and permission handling. Do not mistake an architecture mismatch for a subscription or network problem.

Open the disk image, move the app to the Applications folder, and launch it from there. Do not run it from the mounted installer long-term or drag individual files out of the app bundle. A consistent path helps keep permissions and updates in order. If macOS displays a security warning, confirm the download source and file, then follow the security settings process provided by the system. Do not disable system-wide security protections to bypass all checks.

Import a Subscription and Establish a Basic Connection

Open v2rayN, go to subscription group settings, enter a name and the full URL, enable the group, and save it. After updating, select a configuration to make it active. Desktop setup follows the same general process across platforms, but menus and shortcuts may differ. Look for the action by name rather than following mouse instructions written for another system. If the update fails, first check whether the provider is reachable directly; use an existing working proxy only if needed. Do not depend on a connection that is not yet set up.

When starting for the first time, check that the core runs successfully before enabling the system proxy. If the log reports that a program cannot execute, lacks permissions, or is missing a file, resolve the local startup problem first. The system proxy can receive requests only after the core listens on a local port. Pointing proxy settings at a port with no running service will make apps hang or fail, which can look like a remote connection problem.

Understand Proxies Saved Per Network Service

On macOS, proxy settings are associated with network services. Wi-Fi, Ethernet, and other services may each have separate settings, so check the proxy state after switching networks. In System Settings, identify the active network service and verify the local address and port for its HTTP, HTTPS, or SOCKS proxy. If the client says the proxy was set but your browser is not using it, make sure you checked the active service, not one that is disconnected.

Some apps use their own network stack or proxy settings and do not fully follow the system proxy. For these apps, first check whether they support manual proxy settings. Enter the protocol and port the client is actually listening on; do not put a SOCKS port in a field that accepts only HTTP proxies. The system proxy affects only apps that honor it. If you need to route other traffic, consider TUN rather than repeatedly switching system proxy modes in an attempt to cover every app.

TUN Permissions and Other Network Tools

Enabling TUN may require elevated permissions or a helper component specified by the client; the steps depend on the current build. Follow the prompt to authorize it, then check whether the virtual interface is created. Do not apply driver installation steps from another operating system or change permissions inside the app bundle to get around a prompt. If startup still fails after permission is granted, check the first error and determine whether the helper failed, a port is in use, or virtual interface creation failed.

Work devices may already have network filters, an enterprise VPN, or device management policies. When these run alongside TUN, routing and DNS ownership get more complex. If the device is managed, follow your administrator's requirements. On a personal device, temporarily disable other network-routing tools and test with one setup at a time. Do not change the priority of several VPNs at once; even if connectivity returns, you will not know which change fixed it.

After waking from sleep, first check that the active network service has a valid address, then check the proxy state. If problems occur only after switching networks, disable traffic routing, test the original connection, and then enable it again. If you still cannot connect after closing the client, check whether the active service retains a local proxy. When moving to a new Mac, you can import subscriptions and routing rules, but confirm the local port, system permissions, and chip compatibility again. Do not assume the other machine's network service state will transfer as-is.

Linux: Package Types, Desktop Proxy, and Permissions

Install v2rayN for Your Distribution and Architecture

Get v2rayN from the Linux downloads. Choose deb or rpm for your distribution and confirm whether your device uses x64 or arm64. The package type depends on the system's package manager, while the architecture depends on the device; both must match. Whether the desktop interface launches also depends on your graphics environment and system dependencies. A matching file extension alone does not guarantee that all runtime requirements are met.

Whenever possible, open the downloaded package in your graphical software installer. Review its dependencies and installation result, then launch v2rayN from the application menu. If installation fails, check whether the issue is a missing dependency, an architecture mismatch, or an unreadable file; do not force installation while skipping dependencies. If system repositories are not configured, fix the package manager first. Save client settings before removing an old package or installing a new one. Do not manually clear system network settings to fix an ordinary software installation error.

Import a Subscription and Check Directory Permissions

Launch the client as a regular user, open subscription group settings, add the URL, update, and select an active configuration. The current user needs read and write access to the client configuration directory. If the GUI was previously launched with elevated privileges, it may have left files with the wrong owner; settings may then fail to save or revert on every launch. Check the specific directory and its owner rather than recursively changing permissions across your home or system directories.

When the core will not start, logs are usually more specific than the interface message. First confirm the companion core files exist and are executable, then check whether a security policy blocks them, and finally see whether the listening port is already in use. Successful software installation and successful core startup are separate stages. Do not immediately change the server address after seeing a connection failure: if the local core is not running, changing remote settings cannot fix a local execution permission problem.

Desktop Proxy Settings and App Settings Are Separate

Linux does not have a single system proxy interface that behaves identically across every desktop environment. Desktop network settings may be honored by a browser but ignored by terminals, containers, or background services. After enabling the v2rayN system proxy, test it in the apps you actually use. For apps with manual proxy settings, enter the loopback address and the client's actual port, and specify HTTP or SOCKS as appropriate. Do not assume every app automatically shares the desktop settings.

Proxy environment variables in a terminal usually affect only the current process and its child processes. They do not replace desktop settings or automatically affect apps that are already running. The example below shows a temporary setup: replace the port with the client's actual HTTP proxy port, then run a tool that supports these variables in the same terminal. Remove the variables when you finish testing. For SOCKS, also confirm that the tool can send domain name resolution through the proxy.

export http_proxy="http://127.0.0.1:10809"
export https_proxy="http://127.0.0.1:10809"
export no_proxy="localhost,127.0.0.1,::1"

# Remove the temporary settings from this terminal after testing
unset http_proxy https_proxy no_proxy

TUN, DNS Resolvers, and Container Boundaries

TUN creates a virtual network interface and changes routes, which may require network management permissions. Follow the authorization flow in the current client; do not make running the GUI with maximum privileges your default approach. After enabling TUN, test basic connectivity, then a destination expected to use the proxy. If the process runs but the virtual interface is missing, investigate permissions first. If the interface exists but all access fails, check routing and DNS rather than repeatedly reinstalling the app.

Different Linux distributions may use different components to manage DNS, and edits to resolver files may be overwritten immediately by network services. Configure DNS through the client or current network manager, and record the original state. Containers, virtual machines, and separate network namespaces may not inherit the host's proxy or routes; a working browser on the host does not prove that a container uses the proxy. Before configuring one of these environments, identify its gateway, resolver, and reachability to the host's listening address.

Before upgrading, keep a working configuration and close the client. After upgrading, check the core path, listening port, and permission prompts again. If startup fails after desktop login but works when launched manually, check whether it starts before the network is ready or runs in a different environment than the interactive session. Verify installation, saved configuration, core startup, app traffic, and destination access in order. This breaks Linux environment differences into specific issues and avoids aimless system changes.

Android: Configure v2rayNG and v2flyNG

Choose a Core and Installation Package

Open the Android downloads. v2rayNG, which uses the Xray core, is the recommended starting point; v2flyNG is an alternative with the V2Fly core. Choose after checking what your service configuration requires. Most current arm64 devices can use the matching package; if you cannot confirm the architecture, choose a universal package. Do not infer processor architecture from the Android version or use repeated installs of both clients to test protocol compatibility. Checking the configuration fields is more useful.

Install through the system installer. If prompted to allow installs from a source, grant only the required permission to the file manager or browser you are using, and revoke it later if you prefer. If the installer reports an incompatible package, check the architecture, system requirements, and any existing app. If it reports a signature conflict, back up the old app's configuration and decide whether to change the installation source. Uninstalling can delete subscriptions and rules, so it should not be the first step every time an update fails.

Manage Subscriptions and Import Individual Links

In v2rayNG, open the subscription group options, add a group, enter a name and complete subscription URL, save, and update. For a single share link, use the clipboard import or QR scan option instead of pasting it into the subscription URL field. The v2flyNG menu path may differ, but the distinction is the same: retrieving a set of configurations versus importing one configuration. If menu labels change, choose the option based on what it does.

After updating, select the configuration you want and tap Connect. If the list is empty, check that the group is enabled, the URL is complete, and no filters are hiding entries. Android browsers may copy a page title instead of a share link or omit part of a long URL, so inspect the full text. Subscriptions may contain user-specific parameters; keep them on your personal device. When changing phones, use a secure backup method instead of sharing the full URL in public messages or screenshots.

Android VPN Permission and App Scope

The first connection usually prompts for Android's VPN permission, which the client needs to route traffic through the system interface. Approve it, then check the connection status and logs. This is not the same as selecting “Set System Proxy” on desktop: Android can send traffic from selected apps to the client, which then routes it direct or through the proxy. A VPN indicator in the status bar only confirms that the interface is active; it does not prove that every remote configuration is reachable.

Per-app proxying and routing rules are different. The per-app list determines which apps enter the traffic interception scope; routing rules determine the outbound path for traffic that enters. With an allowlist, an unchecked target app will not use the proxy. With a bypass list, the selected apps are excluded instead. Read the current mode carefully before changing it, then test with one target app to avoid misreading a long list.

Background Restrictions, Network Changes, and Conflicts

Some Android builds restrict background activity, so a disconnect after screen lock may be caused by battery settings. First check whether the system stopped the client, then grant the background permissions allowed by your device's policy. Background access does not guarantee that every connection will stay up indefinitely; after switching from Wi-Fi to mobile data, existing connections may need to be re-established. If the issue happens only after locking the screen or changing networks, check process status and network changes before altering protocols.

The system VPN interface may be occupied by another network tool. If enabling another app disconnects the existing connection, investigate a conflict. Troubleshoot with only one traffic-routing tool active. Private DNS, network filters, and per-app settings can also affect resolution or which traffic is routed; record the original settings and test one change at a time. Do not permanently disable all network protections. Once you identify the cause, make a limited change that you can undo.

For testing, access a real destination in the target app, then check the logs for DNS resolution and connection results. If the client test succeeds but one app fails, check the per-app scope, the app's own proxy settings, and its protocol requirements. If all apps fail, revisit the service configuration and DNS. After moving to a new phone, check VPN permission, battery restrictions, and the app list again; these system settings do not fully migrate with a subscription. For quick steps, see the Subscription Import Guide.

Routing, DNS, and Domain Matching

Define the Traffic and Outbound Path Before Setting Up Split Tunneling

After a request enters the client, routing rules choose whether it goes direct, through a proxy, or is blocked. Rules may match domains, destination addresses, ports, or protocols, and their order and priority affect the result. A common approach is to put LAN rules first, followed by specific destination rules, and then a default action. If two rules could match, check how the current core evaluates them rather than assuming a longer domain automatically takes priority.

Domain rules work only if the core knows the target domain. If an app resolves a name itself and sends only the resulting address, the client may see only an IP address. Sniffing can extract hostnames from some traffic, but it does not work with every protocol and is not a substitute for DNS planning. Check how a request reaches the client before choosing a domain or address rule. A rule can be written correctly and still never match if the required input is unavailable.

Separate Service Address Resolution from Destination Resolution

At least two kinds of DNS resolution may be involved: resolving the proxy service address before connecting, and resolving the destination domain when accessing a site. The first must not depend on a proxy connection that has not been established, or startup can get stuck in a loop. Plan the second according to whether traffic should go direct or through the proxy. The system resolver, app-level DNS, and core DNS may also all be in use, so changing one DNS setting in the client may not change every app's lookup path.

Remote DNS describes which resolver to use; it does not guarantee that DNS requests go through the proxy. Check how traffic to the resolver is routed and whether the client captures queries from the app. Encrypted DNS changes how queries are transmitted, not their outbound route. If routing sends the resolver's address direct, queries may still leave through the local network. Verify resolver selection and the resolver's connection path separately.

Configuration Snippet for Understanding Rule Structure

The following Xray/V2Fly-style routing fragment illustrates the relationship between rule fields and outbound tags. It is not a complete runnable configuration. Merge it into a custom configuration that uses this format, and make sure the direct outbound is actually tagged direct. A GUI may generate a different tag, so do not assume they match. For cores that use another configuration format, use the corresponding settings instead of inserting this fragment into an incompatible file.

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

AsIs means the routing stage does not actively resolve a domain to an IP address as part of that policy; it does not mean the connection will never need DNS later. Using geoip:private also depends on the relevant rule data being available. If logs report a missing data file, fix resource loading rather than deleting all split-routing rules. The example domains illustrate structure only. Use the destinations your setup requires, and avoid overly broad rules that could send large amounts of traffic direct by mistake.

FakeDNS and the Limits of Leak Testing

FakeDNS uses virtual addresses to maintain domain mappings. Both the DNS query and the subsequent connection must follow a compatible processing path. Access may fail if an app bypasses the client's resolver but sends a real address to a rule expecting a virtual one—or receives a virtual address but its connection is not captured. Before enabling FakeDNS, confirm the TUN DNS interception method and core support. It is not a one-click option that works for every app.

To investigate DNS paths, check client logs, system resolver settings, and the test app together. A test page's reported DNS exit is a clue, not proof of how every query on the device is handled. Test system DNS, browser-specific DNS, and TUN separately, and verify both direct and proxied destinations. See DNS Leak Testing and Configuration for details. If something breaks, restore a working resolver first, then add features one at a time so you retain a way to troubleshoot.

Choose Between System Proxy and TUN

Consider the Traffic Entry Point Separately from the Outbound Route

A system proxy provides an address that apps can use to send requests to the client. TUN creates a virtual network interface and routes matching traffic into the client. They solve different traffic-entry problems, so there is no simple “which is faster?” answer. If you mainly use a browser, start with the system proxy because it is easier to observe. Consider TUN when an app ignores the system proxy or you need to handle a wider range of traffic.

A wider TUN interception scope does not mean all traffic has to go through a remote proxy. After traffic enters the virtual interface, routing still chooses its outbound path; LAN traffic, selected destinations, and some system traffic can go direct. Conversely, choosing a global proxy route cannot make an app use the proxy if its traffic never enters the client. Troubleshoot in two stages: first ask whether the request reached the client, then where it went.

Checks Before Enabling TUN on Desktop

Establish a basic connection with the system proxy first. Confirm that the active configuration, core, and subscription work before preparing TUN. Note your current network interfaces, default gateway, and any other VPNs, then quit potentially conflicting tools. Grant the permissions needed to create the virtual interface as prompted by the client. After enabling TUN, check the logs for interface setup and routing. If the toggle is on but the log reports an error, trust the startup result, not the toggle's appearance.

Settings such as automatic routing, strict routing, and DNS interception affect scope and compatibility. Check the documentation for the core you are using to understand their exact behavior. Strict routing may reduce traffic bypass, but can also affect LAN access, virtual machines, or system services. Do not enable every advanced option at once. Start with the client-recommended basics, then add what you need based on actual gaps. After each change, test a proxied destination, a direct destination, and LAN access, and keep a way to roll back.

Prevent the Service Connection from Routing Back into Itself

Connections to the proxy service also generate network traffic. TUN must handle them correctly so the core's own connection is not sent back through the same entry point, creating a loop. Clients and cores often provide built-in options to exclude interfaces, bind an outbound route, or manage routing. Prefer these integrated settings. If logs show repeated connections and resource usage rises without access to destinations, check for routing loops and conflicts with other traffic-routing tools instead of changing only the remote configuration.

Using a domain for the service address also involves startup DNS. If DNS queries are forced through a proxy that is not yet connected, the service address itself may never resolve. Keep a reachable DNS path for the service address, then resolve destination domains according to your intended policy. With multiple network interfaces connected, check the actual default route. Some apps bind to an old interface and may need traffic routing restarted after a network change.

UDP, LAN Access, and App Compatibility

UDP support differs across the system proxy, local client entry points, and remote protocols; the remote service may also impose limits. Enabling TUN only routes traffic into the core—it does not provide UDP support throughout the entire chain. If webpages work but voice, games, or other apps fail, identify the traffic type they use, then check the entry point, core, remote protocol, and server policy. Working TCP access alone does not rule out a transport issue.

LAN access depends on address routing, while device discovery may also use broadcast or multicast. Do not assume a LAN bypass rule will fix every discovery issue. First test direct access to a known LAN address to distinguish an address connectivity problem from a discovery problem. Include virtual machine and container subnets in your plan to avoid overlap with the TUN address pool. If subnets conflict, adjust the relevant configuration instead of making every destination go direct.

Keep a Recovery Path When Exiting or Switching

When testing is complete, disable TUN first, clear any system proxy you no longer need, and then quit the client. Some setups can use both entry points, but for initial troubleshooting, use only one to reduce uncertainty about the traffic path. After a network change, waking from sleep, or an upgrade, check the virtual interface and default route again. If problems remain after TUN is disabled, check for leftover proxy and DNS settings. For background and more usage scenarios, see v2rayN TUN Mode Explained.

Common Configuration Problems and Step-by-Step Troubleshooting

Identify the Failing Layer First

Break the problem into six stages: app installation, core startup, subscription retrieval, service connection, traffic capture, and routing or DNS. Record when it happened, your current network, and the last change you made, then review logs from the same time period. Find the earliest meaningful error instead of getting distracted by repeated follow-on failures. A connection status, a virtual interface, or a passing test confirms only its own stage—not the entire path.

If the original network still fails after you close the client, first restore system proxy, DNS, and interface settings, then check the network itself. If the original network works but the core will not start, check local files, permissions, and ports. If the core starts but every configuration fails, check the clock, network restrictions, and shared parameters. If only one configuration fails, focus on that configuration. Narrowing the issue by scope is more useful than repeatedly switching clients.

Subscription Update Failed or Returned an Empty List

First check that the URL is complete, query parameters are intact, and it does not contain spaces or a copied page title. Then distinguish a network error from a content error. If the provider cannot be reached, check your network and update method. If it is reachable but parsing fails, confirm that the response uses a subscription format supported by the client. A login page, error page, or rate-limit notice may be returned as plain text, so a successful fetch does not necessarily mean the content is valid.

If updating without a proxy fails and you already have a working connection, try updating through the proxy. If this is your first setup and no connection is available, do not rely on that option. If the list is empty after an update, check that the group is enabled, review filters, and inspect the provider's response. Keep old working configurations until you have verified the new ones. For more scenarios, see the Troubleshooting FAQ. Treat update failures and connection failures as separate problems.

Configuration Imported but Connection Fails

Compare the configuration against the complete parameters from your service provider. Check the address, port, user ID, transport, security settings, and service name. A share link may compress the displayed information, so inspect the actual values in the edit view. Similar-looking fields may have different meanings; do not assume the server address is also the value for every security field. For certificate errors, check the system clock and configured destination name instead of disabling validation to hide the issue.

Check core compatibility separately. Accepting a share link does not mean the current core supports every option it contains; missing fields during import or old settings left over from a migration can also cause a mismatch. Start with the original subscription configuration as a baseline before making manual changes. If a core change causes failure, restore the last working core and compare their supported features. Randomly combining parameters is not a reliable troubleshooting method.

Browser Works but Other Apps Fail

First check whether the failing app uses the system proxy. If it supports manual proxy settings, verify the proxy protocol, loopback address, and actual port. If it does not, consider TUN or the per-app traffic scope on Android. If traffic reaches the client, check the routing match and DNS. App-level encrypted DNS, cached addresses, or a different traffic type can produce different results. Start a new connection for each test so an existing session does not mask a change.

Do not change the local listener to bind to every network interface to fix an ordinary app problem. For apps on the same device, the loopback address is usually enough. Allowing other devices to use the local proxy is a separate requirement that needs access controls and firewall planning. If a port is already in use, identify the process using it, stop the conflicting process or choose an available port, and update the app settings to match. Changing the port on only one side will create another connection failure.

Restore a Working State Before Reporting the Issue

If failures are intermittent, note whether they coincide with screen lock, sleep, network changes, subscription updates, or enabling another network tool. Test the same destination repeatedly and change one variable at a time. To recover, first disable traffic routing and restore the original network; then import the most recent working backup. When reporting the issue, include your operating system and architecture, client name, core type, steps already tried, and a redacted error excerpt. Never share full credentials. If a term is unclear, see the Glossary, then return to the relevant section.