Documentation / Cross-Platform Setup

V2Ray Setup Guide

Install v2rayN, v2rayNG, and v2flyNG, import subscriptions, and route traffic through them.

Use this page as a reference for platform-specific permissions, architectures, and network limitations. For your first setup, follow the quick start guide to establish a connection, then return to the relevant section to fine-tune your settings. Client menus may change between releases; rely on the names and logs shown in your installed version.

Before You Configure

Before You Begin: Choose a Platform and Configuration Source

Understand the Client, Core, and Server Configuration

For desktop systems, use v2rayN on Windows, macOS, or Linux. On Android, v2rayNG with its Xray core is the usual choice; consider v2flyNG if you specifically need the V2Fly core ecosystem. The graphical client stores settings, updates subscriptions, generates runtime parameters, and controls the core process. The core handles the actual connection. Installing a client does not provide a working server or create a subscription. Before you begin, obtain a valid configuration from a legitimate source and confirm which protocol and transport it supports.

The server address, port, user ID, transport, and security settings must be used together. A matching protocol name does not mean you can combine one configuration with another configuration’s TLS settings, path, or server name. VLESS and Trojan, for example, use authentication fields and outer security parameters for different purposes; leaving out either can cause connection timeouts. If a link will not import, first identify whether it is a single server share link, a subscription URL, or a complete configuration file, then use the matching import option instead of repeatedly pasting it into the same field.

Check Device Architecture, Time, and Network

Check your system information before downloading. On Windows, look at System type; on macOS, check the chip under About This Mac; on Linux, confirm both the processor architecture and package format used by your distribution. Most newer Android devices use arm64, but check the device’s supported ABI rather than relying on its age. Package format and processor architecture are separate: deb and rpm determine how a package is installed, while x64 and arm64 determine whether the program can run. Match both labels when choosing a download.

Enable automatic time synchronization and check that your time zone is correct. An inaccurate system clock can cause certificate validity checks to fail and affect time-based authentication. Then turn off proxies and open a familiar website to confirm that the underlying network works. If it does not, troubleshoot Wi-Fi, the gateway, or a network sign-in page first. Temporarily quit other proxy and VPN tools to prevent them from repeatedly overriding the same system settings. Managed devices may also have administrator-enforced proxy policies that cannot be resolved by toggling settings.

ItemWhat to CheckRisk if Not Checked
Client packagePlatform, architecture, and package formatThe client may fail to install or launch
Configuration sourceValid address, active account, and matching formatImport or authentication may fail
System environmentAutomatic time sync, working network, and existing proxiesCertificate errors or traffic conflicts

Start from a Known-Good Baseline

For your first run, import just one configuration, select one server, and use the client’s default routing. Don’t enable TUN, custom DNS, remote rules, and multiple experimental options at the same time. After each change, retry the same test destination and note what changed. This keeps any issue tied to the layer you just adjusted. Before making changes, save your existing settings or take screenshots, but hide subscription URLs, user IDs, and authentication details. Even a link that looks harmless can grant access to an account.

Decide how you’ll verify the setup: can the browser load the target page, does the client log the connection, and can sites that should bypass the proxy still load? A successful latency test only shows that a specific probe received a response; it does not mean web access, DNS, or every app is configured correctly. The platform sections below follow the same order: install, import, route traffic, and verify. You can jump to your platform, but don’t skip the initial baseline check.

Desktop / Windows

Windows: Install v2rayN and Configure the System Proxy

Choose the Desktop or Classic WPF Version

Go to the Windows downloads page and choose v2rayN. The desktop edition uses a newer cross-platform interface, while the classic WPF edition retains the traditional Windows desktop interface. Choose based on your preferences and compatibility needs; don’t run both versions at once to compare connection performance. The x64 installer currently offered on the downloads page is for compatible system architectures. Read the installer prompts before running it. If a runtime component is missing, install it as directed by the client or installer; don’t download a DLL with the same name from an unknown source and overwrite program files.

After installation, launch the client as a standard user. Opening the main window does not mean the core has started; check the logs for configuration loading and a local inbound listener. Program files and user data may be stored separately, so export your settings using a supported client feature before updating or moving the app. Don’t leave the program in a temporary extraction folder and delete it later, or move the entire directory while it’s running. The next launch may fail to find the core, rule files, or saved settings.

Import a Subscription and Select an Active Server

Open the subscription group or subscription management screen. Add a clearly named group, enter the full subscription URL, save it, and then update. For a single share link, use the matching feature, such as importing from the clipboard; there’s no need to create a subscription group. After updating, check that the expected configuration appears in the list, then select one by double-clicking it or choosing Set as active server from the menu. A server appearing in the list does not mean it’s in use. Check both the active indicator and the core status.

If a subscription update fails, check the logs to see whether it’s a parsing error, authentication failure, or request timeout. Before the first connection is established, updating through the proxy can create a dependency loop. Try updating directly or use another retrieval method permitted by the configuration provider. Don’t disable all security checks just to populate the list. If the update succeeds but the list is empty, check group filters, account status, and the response format. Also make sure the subscription URL didn’t pick up a line break or trailing punctuation when copied.

Start with the System Proxy, Then Consider TUN

After selecting a server, set the system proxy to “Automatically configure system proxy” or the equivalent option in your client. This routes apps that honor Windows proxy settings through the local proxy, but it does not capture all network traffic. Browser extensions and app-specific proxy settings may override it, and command-line tools often ignore the system proxy. Don’t switch servers right away. Check whether the client logs a connection when you make a request to find out whether the request reached the local proxy.

Enable TUN only when you need to route traffic from more apps, and grant the required permissions when prompted. TUN uses a virtual network interface and affects routing and DNS; it is not just another way to display the system proxy setting. For an initial test, turn off the system proxy and use only one traffic-routing method. Once it works, follow the client’s guidance for combining settings if needed. If you encounter driver, virtual network adapter, or routing errors, check the logs, permissions, and other VPN software. Don’t turn off the entire firewall as a substitute for troubleshooting.

Verify the Connection and Restore Settings When You’re Done

Use a browser to visit one destination that should use the proxy and another that should connect directly, then compare the selected outbound routes in the logs. If the browser works but the terminal does not, see how to troubleshoot system proxy and terminal issues separately instead of blaming the server for differences between apps. Before you finish, clear the system proxy, then quit the client. If the browser reports that the proxy cannot connect after an unexpected shutdown, check Windows network proxy settings for a stale address pointing to a stopped local port. Restore the settings before restarting the client and testing again.

Desktop / macOS

macOS: Chip Selection, Permissions, and Network Services

Install v2rayN for Your Mac’s Chip

Open the macOS downloads page and choose arm64 for Apple Silicon or x64 for an Intel Mac. Check the chip under About This Mac rather than guessing from the model name or appearance. After downloading the DMG, open it and drag the app into Applications as directed by the installer. Launch it from there. Running the app directly from the mounted disk image can cause path and permission issues when you eject the image, update the app, or restart, and makes ongoing maintenance harder.

macOS security settings may prevent the first launch. Verify the app’s source and platform, then check Privacy & Security in System Settings for an option to allow it to open. Managed devices may prevent users from granting this permission; ask an administrator for help. Don’t disable system-wide security or remove unfamiliar system attributes to run a single app. If the app reports an architecture mismatch, return to the downloads page and select the correct build instead of treating every launch error as a permissions issue.

Import a Configuration and Check the Core

In v2rayN, create a subscription group, save the URL, and update it. Then set one configuration as the active server. Use the clipboard import option for a single share link; for a complete file, first confirm that it is compatible with this client. Don’t enter a core-specific JSON file as a subscription URL. After importing, check the logs to make sure the core has not exited. Some issues affect only the background process, while the main window remains usable, so an open interface alone does not confirm that installation is complete.

Test the connection with the default or basic routing before adjusting DNS and routing rules. Before switching cores, confirm that the selected core supports the protocol and transport in your configuration. A configuration with the same display name may still generate incompatible parameters. If switching cores causes unknown-field or configuration-parsing errors, restore the previous core and review the client’s generated-configuration messages. Avoid repeatedly overwriting settings in both the UI and a hand-edited file; your changes may be reverted the next time the client saves its configuration.

How System Proxy Settings Map to Network Services

macOS proxy settings are associated with network services. After enabling the system proxy, check which service is actually in use: Wi-Fi, Ethernet, or another interface. If only some apps connect directly after switching interfaces, the new network service may not have the corresponding proxy settings. HTTP, HTTPS, and SOCKS fields in System Settings have different purposes; don’t swap their ports just because they all use a local address. If the client configures them automatically, keep the generated settings until you’ve confirmed the connection, then make any necessary manual adjustments.

Browsers can use the system proxy, but extensions or app-specific network settings may override it. Terminal programs usually need their own proxy options or environment variables; a proxy icon in the menu bar won’t change their behavior. After switching networks, create a new test connection, as existing connections may continue using the old route. Use the same destination for each test and check the logs. This helps distinguish the current settings from cached pages, existing connections, or background retries.

TUN Permissions, Sleep, and Recovery

If you need TUN, follow the client’s prompts to grant the required permissions. Creating a virtual interface and changing routes typically require additional privileges; the exact process depends on the client. If all network access stops after enabling TUN, turn it off to restore connectivity, then check the logs for interface creation, route changes, and DNS errors. Don’t try to fix this by enabling full traffic routing in another VPN at the same time; the two may compete for the default route and make the problem harder to reproduce. Security software on work devices may also restrict network changes.

Before quitting, clear the system proxy and check whether the browser can connect directly again. If a page reports that the local proxy cannot connect after the app has exited, check for leftover settings in the current network service’s proxy configuration. Don’t delete the network service or reset all network settings as a first step. Restore only the traffic-routing layer while keeping subscriptions and routing settings; this limits the scope of the change. Once connectivity is restored, re-enable one client feature at a time to test it.

Desktop / Linux

Linux: Packages, Desktop Proxy, and Permissions

Match the Architecture and Distribution Package Format

On Linux, v2rayN is the desktop client. On the Linux downloads page, first choose deb or rpm, then select x64 or arm64. Debian and Ubuntu usually use deb packages, while Fedora commonly uses rpm; confirm the format with your system’s package manager. You can check the architecture and system ID with the read-only commands below. The output x86_64usually corresponds to x64, and aarch64usually corresponds to arm64. Renaming a package file does not convert it to another format.

uname -m
cat /etc/os-release

After downloading, open the package with your desktop software installer or install it using your distribution’s documented package manager. If dependencies are missing, check the specific packages reported by the package manager, then confirm that your desktop environment and OS version meet the requirements. Don’t copy system libraries from another distribution into system directories. Installation issues and client configuration issues are separate stages: resolve the package, dependencies, and architecture first; then troubleshoot subscriptions and core parameters. Handling both at once adds unnecessary variables.

Launch and Import as a Standard User

After installation, launch v2rayN from the application menu and set up the subscription group, save its URL, and update as a standard user. When the update succeeds, select an active server and check the core logs for a listener. If the desktop icon does not open the main window, use your desktop environment’s application log viewer to inspect the error. Don’t immediately launch the entire interface as an administrator. Starting it under a different account can create a separate data directory with different file ownership, which may prevent your standard user from writing to the original configuration.

If you previously launched the app with elevated privileges and the configuration is now read-only, quit the app, identify its actual data directory, and repair that directory’s ownership using your system’s administration tools. Don’t recursively loosen permissions across your entire home directory. Subscription URLs and exported configurations are sensitive; limit access to the accounts that need them. When updating the client, keep user data and check that the core path and rule resources are still available afterward. A successful GUI update does not guarantee that external file paths remain valid.

Understand What the Desktop System Proxy Covers

Linux does not have a single system proxy switch that every application shares. Desktop environments such as GNOME and KDE have their own proxy settings, while apps may read only environment variables, separate configuration files, or launch options. After v2rayN successfully updates the desktop proxy, your browser may work while terminal requests still connect directly. Treat this as an application-level difference: check whether the request reached the client, then decide whether to configure the individual tool or use TUN to capture more traffic.

The command below sends a request to an example site through the local SOCKS endpoint. It checks the path from the tool to the local proxy. Replace the port with the one the client is actually listening on. The example uses socks5h, which delegates destination hostname resolution to the proxy. A successful test only confirms that this request used the specified endpoint; it does not prove that the desktop proxy, other terminals, or every app is configured correctly. If the connection is refused, first check that the core is running and the port matches.

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

TUN Permissions and Network Manager Conflicts

TUN needs access to a virtual network device and the ability to manage related routes. The required permissions depend on how the client is packaged and your system’s policies, so use the client’s built-in permission flow. Don’t grant broad elevated permissions to the entire installation directory. If TUN fails to start, check whether the virtual device is available, whether permission was denied, and whether another VPN conflicts with the default route. A container or restricted desktop session may not have the required device or permissions at all. Repeatedly toggling the setting won’t solve that, and you should not weaken system-wide security to work around it.

On Linux, also consider the boundary between the system resolver and the client’s DNS. Your system may resolve queries through a local stub resolver, while TUN can route DNS through a different path. If only hostnames fail, compare system resolution with a request through the proxy. Don’t change the network manager, resolver, and client settings all at once. After quitting, check that the desktop proxy and temporary environment variables have been restored. If only one terminal is affected, inspect that session’s variables instead of reinstalling the client.

Mobile / Android

Android: VPN Permission and Background Operation

Choose v2rayNG or v2flyNG

v2rayNG is the usual choice on Android and uses the Xray core. Choose v2flyNG if you specifically need the V2Fly core ecosystem. The Android downloads page offers arm64 and universal packages for both clients. Most newer devices support arm64, but check the device’s actual system architecture and supported ABIs. If you’re unsure, consider the universal package. Similar-looking interfaces do not guarantee that the apps support the same features; protocol, transport, and security options depend on each core.

When installing an APK, Android may ask you to allow your browser or file manager to install apps. Grant permission only to the source you’re using, and revoke it afterward if you like. If Android says the app cannot be installed, check the device architecture, available storage, and whether an existing app has a conflicting signature; a failed update does not necessarily mean the package is corrupt. Before uninstalling and reinstalling, back up any settings you need using the client’s built-in tools. Uninstalling may remove groups, routing, and app selections, which may not return automatically.

Import a Subscription and Grant VPN Permission

Open the subscription settings, add a group, and enter the full URL. Save it, return to the list, update the subscription, and select the server you want to use. Import a single share link using the clipboard or QR code option, but remember that a QR code may contain account details and should not be shared publicly. After import, check the protocol and required fields rather than relying on the display name. If you have multiple groups, make sure the current filter isn’t hiding the new configuration. An update does not automatically mean the active server has changed.

When you tap Connect, Android displays a VPN permission prompt. Approve it so the client can use Android’s VpnService to route traffic. The VPN icon means the system has created the interface; it does not confirm that the remote server authenticated successfully or that web pages will load. Check the client logs and visit a test destination. Standard apps usually have only one active system VPN connection at a time. Other VPN, ad-blocking, or network protection apps may be using it, so decide which one to keep before trying again.

Routing, Per-App Proxy, and Local Proxy Endpoints

Connect using the client’s default routing first, then configure per-app proxying if needed. Different interfaces may use “Proxy selected apps” and “Bypass selected apps” to describe opposite modes, so check the selected mode before saving. When choosing a browser, consider whether a page launches an external app, download manager, or system service; these may not share the browser’s app identity. To troubleshoot a specific app, temporarily broaden the traffic-routing scope. If that makes it work, narrow the scope one app at a time to find what was left out.

Android VPN routing is different from the desktop system HTTP proxy. You generally don’t need to enter a local proxy in your Wi-Fi advanced settings. Doing so may break network access after the client stops. The local SOCKS port shown by the client is intended for apps that explicitly support proxies; it is not automatically accessible to other devices on your LAN. Don’t bind it to all interfaces just to test. Sharing it across devices introduces new access control, network isolation, and permission concerns.

Battery Management, Network Changes, and Reconnecting

If the connection works in the foreground but drops after the screen has been locked for a while, check battery optimization and background activity restrictions first. Settings vary by manufacturer; in the app info, allow the background operation you need and keep the foreground notification if necessary. Excluding the app from battery saving only reduces the chance that it will be stopped in the background; it won’t fix a bad server or DNS configuration. Logs that stop while the screen is off and resume when you reopen the app point to background management. Distinguish this from persistent handshake errors.

After switching between mobile data and Wi-Fi, make sure the network sign-in is complete before reconnecting. Networks may handle UDP, DNS, or destination ports differently, so results on one network don’t establish the server’s status on another. If only background connections drop, see v2rayNG battery optimization and per-app settings. If neither network can load pages, use the log-troubleshooting steps at the end of this guide rather than repeatedly reinstalling the app.

Cross-Platform / Configuration Lifecycle

Subscription Management: Update, Select, and Back Up

Subscription URLs vs. Share Links

A subscription URL usually retrieves a set of server configurations over the network, while a single share link describes one server. Both can be copied to the clipboard, but they use different import flows: save subscriptions in a group so you can update them, and import share links using the matching option. A web address is not necessarily a subscription URL. Account pages, help pages, and login redirects are not configuration sources. If an update fails to parse, ask the configuration provider what the URL is for and what format it returns.

Subscription URLs often contain access credentials. Anyone who can retrieve the configuration may gain access to the same account resources. Don’t post a complete URL in public feedback, online parsing tools, or screenshots. When reporting an issue, include only the error type, client name, and necessary non-sensitive details. Apply the same care to QR codes, exported files, and backup folders. If a URL has been exposed, regenerate it or revoke it through the provider’s management tools. Deleting local history does not invalidate copies elsewhere.

Separate the Subscription Update Route from the Traffic Route

Direct and proxied updates determine how the subscription request is fetched; they do not set the server’s routing mode. If you have no working server yet, updating through the proxy may not work. If an existing connection works but direct access to the subscription service fails, an update through the proxy may help. Check whether the result is a request timeout, authentication rejection, or content-parsing error. Changing the update route usually won’t fix an explicit authentication error; check account permissions and whether the URL is still valid.

Don’t clear the existing list immediately after an update fails. Keep configurations that may still work, note the group and error, and check whether the current network can reach the subscription service. Some clients retain old configurations, while others may rebuild the group’s entries during an update; check the interface and results to find out what yours does. Be especially careful editing entries generated by a subscription, since the next update may overwrite your changes. For configurations that require persistent custom settings, use the client’s supported duplication or separate management features.

Check the Active Server After an Update

A successful subscription update only confirms that fetching and parsing completed. It does not guarantee that the active server still exists or can be reached. After updating, check the active indicator, protocol, and group filter, then send a real request. Display names can be duplicated or changed, so they aren’t a reliable way to identify the same configuration. Subscription updates may also change a server’s port, transport path, or security parameters. If problems start after an update, first check whether the client loaded the new runtime configuration.

Latency tests, connectivity tests, and loading an actual webpage are not equivalent. Results vary with the test destination, DNS resolution, and probe protocol. A server may respond to a probe but still fail to reach a particular site. Don’t assume the first server after sorting is the best for every situation. Instead, select one configuration and use a consistent destination to check page loading, DNS, and direct-connection exceptions. Choose what to keep based on real use rather than a single test number.

ActionWhat It DoesWhat to Verify
Save subscriptionRecord the source and groupWhether valid content is available
Update subscriptionRefresh server configurationsWhether the active server is still valid
Select a serverChoose the configuration to useCore startup and request results

Include Settings and Their Limits in Backups and Migrations

When moving to another device, export settings and configurations using the client’s supported features. Don’t overwrite the entire program directory with one from another platform. You can reimport a subscription URL, but local ports, routing rules, per-app selections, and system traffic permissions may not transfer. Android app selections, in particular, do not map directly to desktop application paths, so check them again after a cross-platform migration. Store backups where access is restricted; don’t put complete authentication details in publicly synced notes.

For a comparison of subscription and core support, see client comparison. Installing more clients is not a substitute for checking the source and format. If the subscription itself returns invalid content, switching graphical clients will usually lead to the same problem.

Cross-Platform / Traffic Flow

Routing and DNS: Route Traffic First, Then Choose an Outbound

System Proxy, TUN, and Core Routing Work at Different Layers

Before troubleshooting routing, check whether the request reaches the client. The system proxy directs apps that follow system settings to a local endpoint. TUN routes supported traffic through a virtual network interface. Once a request reaches the core, routing rules decide whether it uses a proxy, connects directly, or takes another configured outbound. If an app bypasses the system proxy, changing core rules won’t help. Conversely, if the request reaches the core but a rule sends it direct, there’s no need to keep checking the browser’s proxy setting. Logs help distinguish these cases.

“Global” and “rule” modes may refer to different layers in different clients. A global system proxy setting usually sends more requests to the local proxy, while the core can still choose an outbound based on its rules. In some clients, global routing changes the core’s routing behavior instead. Check whether you’re changing how traffic is captured or how the core routes it. Keep the capture method fixed while testing routing changes, so you can tell which setting made the request work or fail.

Understand Rule Order with a Minimal Example

This Xray-style routing snippet shows how to send an example domain to an outbound named direct. It is not a complete, runnable configuration; define an outbound with the same name in the full configuration first. A client may generate different tags, so adjust the rule to match its output. Routing rules are generally checked in order, and a broad rule near the top can match before a more specific one below it. When adding an exception, check existing rules first instead of appending duplicate conditions.

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

Exact-domain and domain-suffix rules cover different scopes. A rule for the main domain alone may not cover the image, authentication, or API domains a page needs. If the page loads but sign-in fails, check the domains used by the failed requests and which outbound handled them. Don’t switch the entire network to another mode. IP rules have similar limits: IPv4 and IPv6 are separate address families, and handling one does not guarantee that requests over the other will route as expected.

Distinguish System DNS from Core DNS

DNS resolves domain names to addresses, but the system, browser, and proxy core may each use a different resolution path. If the browser has Secure DNS enabled, it may bypass the system resolver. An app can also send a hostname or an already-resolved IP address to a SOCKS endpoint, affecting which domain-based rules the core can apply. First identify where the name is resolved and which outbound handles the query, then decide what to change. Replacing every DNS setting at once turns a diagnosable problem into several unknowns.

This snippet shows the core DNS server array and query address-family settings. It is only a partial example. Access to a server still depends on the network, routing, and client-generated configuration; a public resolver is not a universal answer for every network. If an encrypted DNS endpoint uses a hostname, consider how that hostname will be resolved during startup. Otherwise, DNS queries may depend on a proxy connection that is not yet established, creating a dependency loop.

{
  "dns": {
    "servers": ["1.1.1.1", "8.8.8.8"],
    "queryStrategy": "UseIP"
  }
}

Check LAN, IPv6, and UDP Limitations

If printers, LAN services, or local admin pages become inaccessible after enabling TUN, check whether private addresses and local services have appropriate bypass rules. Don’t route all traffic directly just to fix one LAN address. On IPv6 networks, check which address family the app actually uses; an IPv4-only test does not prove that dual-stack requests work. For voice, gaming, and other UDP apps, confirm that the protocol, server, and traffic-routing method all support the required traffic.

After making changes, reload the core and verify with a new connection. Existing connections may continue using the previous outbound, and apps may cache old DNS results. Refreshing the same page without checking connection logs can make a cache issue look like a broken rule.

Common Configuration Issues / Troubleshooting by Layer

Troubleshooting: From the Local Proxy to the Remote Server

Record What Happens Before Resetting Settings

When troubleshooting, note the client name, operating system, core, traffic-routing method, and failing destination. Specify whether all apps fail or only a particular browser or terminal. Record what changed since the last successful connection: a subscription update, network change, system upgrade, or routing adjustment. Avoid reducing all of this to “connected but not working.” Specific symptoms are easier to diagnose and prevent wasted effort, such as switching remote servers when the local port is not listening or changing DNS when the account has expired.

Turn off TUN and the system proxy, then check that the underlying network works. Restore just one traffic-routing method at a time. If you still can’t get online with both disabled, check for a leftover local proxy address in system settings, Android’s block-connections-without-VPN option, or a network sign-in requirement. Further comparisons are useful only after direct connectivity is restored. Keep subscription and routing backups while restoring settings. Don’t delete all data by default; you may lose a working configuration that could help identify the issue.

Use the Logs to Locate the Failure

If the logs show that a listening port is already in use, first quit duplicate client instances or other programs using the same port. Change the local port only if needed. If you do change it, update browser extensions, terminal arguments, and other explicit proxy settings too. A connection refusal often means the target endpoint is not listening. A timeout only means the connection did not complete within the allotted time; it does not identify whether DNS, the network, or the server is at fault. For configuration-parsing errors, check the fields and core compatibility before changing the system proxy.

If a request does not appear in the logs, check the path from the app to the client: whether the system proxy is active, a browser extension is overriding it, or the app is missing from a per-app list. If the request appears but the handshake fails, check that the server address, port, authentication, transport, and security settings match, and that the system time is correct. If the request uses the expected outbound but only one website has a problem, check that site’s DNS resolution, certificate, and network response. One failed destination does not mean the entire client has stopped working.

SymptomCheck FirstVerify Next
Core exits as soon as it startsConfiguration syntax, port, and runtime permissionsCheck the first specific error
Browser requests don’t appear in logsSystem proxy, extensions, and app traffic routingTest with an explicit local proxy
Request appears, but handshake failsAuthentication, transport, security settings, and timeReimport a known-good original configuration
Only some domains failDNS, routing rules, and destination serviceCompare DNS resolution with the selected outbound

Troubleshooting: Know What to Check

Why can’t I connect after importing a subscription?

Importing only saves the configuration. You still need to select an active server, confirm the core is running, and enable the system proxy or another suitable traffic-routing method. On Android, you also need to grant VPN permission. Once each step is complete, check whether a real request appears in the logs instead of relying on whether an entry appears in the list.

The browser works, but the terminal can’t connect. Should I switch servers?

Not yet. Terminal tools may ignore the system proxy. Check the tool’s own proxy settings, environment variables, and local port. The explicit SOCKS request in the Linux section can help test the local endpoint. If it succeeds, the issue is more likely to be how the terminal inherits its settings than the server itself.

Why do none of my apps have internet access after I enable TUN?

Turn off TUN to restore the baseline, then check permissions, the virtual interface, the default route, DNS, and conflicts with other VPNs. A working system-proxy setup only proves that path works; it does not confirm that TUN routing or DNS is correct. Don’t keep toggling settings while leaving conflicting tools enabled.

Can I ignore certificate verification to fix a connection failure?

Don’t use that as a routine fix. First check the system time, server name in the configuration, transport settings, and configuration source. A certificate error can point to an identity or configuration mismatch. Skipping verification may hide the real problem, so start with the original configuration and the service provider’s instructions.

Include the Right Evidence When Asking for Help

If you need more help, include steps that reproduce the issue, logs from around the time it occurred, and the troubleshooting steps you’ve already tried. Hide the full subscription URL, user ID, password, and other authentication details, and share only what’s needed to diagnose the problem. Higher log levels may record more of the destinations you visit, so restore an appropriate level after collecting logs. Don’t upload your entire configuration directory publicly or use screenshots containing account credentials in place of a written description.

If the client still shows a connection but webpages won’t load, follow the step-by-step checklist for fixing internet access after connecting. To repeat the shortest setup path, return to the quick start guide. To choose an installer for another platform, visit the downloads page. Keeping a known-good minimal configuration is usually more useful for diagnosing future issues than continually adding rules, switching cores, or reinstalling the client.

Download v2rayN