Installation guide · Browse by platform
V2Ray Setup Guide for All Platforms
This guide is organized by platform—Windows, macOS, Linux, and Android—and covers everything from choosing an installer to troubleshooting connection issues. For desktop, start with v2rayN; for Android, begin with v2rayNG, and choose v2flyNG if you need the V2Fly core. Menu names may change between versions, so follow the purpose of each setting and the instructions included with your current package.
If you’re setting things up for the first time and want a straightforward path to your first connection, start with the quick-start guide. Return to the relevant section here for help with architecture, permissions, routing, or subscription updates. Choose a package for your operating system on the client downloads page. This guide doesn’t provide server settings or subscription URLs as built-in client content.
Before you begin: setup basics
Know the difference between the client, core, and connection details
The graphical client stores server details, organizes subscriptions, builds configurations, and controls runtime status. The core processes connections according to that configuration. v2rayN is the desktop management interface; supported protocols depend on the core you choose. v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Similar-looking settings don’t guarantee that both core variants support every extended parameter. Check which core your connection details require before choosing a client.
Installing a client doesn’t give you a working server. You’ll need a subscription URL from a trusted source or a configuration containing the server address, port, user ID, transport, and security settings. Subscription URLs often grant access, so protect them like passwords. When asking for help, don’t share the full URL, QR code, or user ID. Even a screenshot showing only query parameters may expose the configuration.
When entering settings manually, keep three easily confused hostnames distinct: the server address tells the client where to connect, the TLS server name is used for the certificate and handshake, and the HTTP or WebSocket Host is used by the relevant transport. They may match, but the server may specify different values. Don’t replace them with the same hostname just because the address doesn’t look like a familiar website.
Check your system architecture and where files are stored
Choose a package that matches your operating system, processor architecture, and package format. x64 is common on Intel and AMD desktop processors; arm64 uses a different instruction set, so don’t choose based on how new the device is. On Windows, check System type under About; on macOS, check the chip under About This Mac; on Linux, query the machine architecture. If you’re unsure about your Android device’s processor support, check its specifications before considering a universal package.
Choose a location where your account can write files and where you can keep the client long-term. If the package needs extracting, extract it fully before launching it; don’t run it from a temporary view inside an archive utility. Configuration and logs may be stored in the application folder or a user data folder, depending on how the client was distributed. Before upgrading, export any configuration you need and note where the existing data is stored. Copying only the application files may leave subscriptions and routing settings behind.
| Platform | Check first | Before your first setup |
|---|---|---|
| Windows | x64, desktop, or WPF build | Install or extract the full package and check runtime requirements |
| macOS | Apple Silicon or Intel | Move the app to Applications and handle the first-launch prompt |
| Linux | Architecture, deb, or rpm | Check dependencies, desktop environment, and privilege requirements |
| Android | arm64 or universal package | Allow this installation and approve the VPN request |
Start with a repeatable test
Before the first setup, quit other proxies, VPNs, and tools that take control of network traffic, and save a screenshot of your current system proxy settings. Confirm your regular connection can reach a known working website, and check that your system date, time, and time zone are correct. That gives you a clean baseline for distinguishing existing network problems from changes caused by the new configuration, instead of guessing while several network components are running at once.
For your first test, use one server and one traffic-capture method: on desktop, start with the system proxy; on Android, approve the VPN request. Leave custom DNS, complex routing, and LAN sharing off for now. Once connected, add features one at a time and test the same app and address after each change. Note what you changed, the exact error, and when it occurred. That’s far more useful than simply saying it still doesn’t work.
Windows installation and system proxy
Choose the desktop or classic WPF build
Start by choosing v2rayN from the Windows download page. The desktop build uses a cross-platform interface, while the classic WPF build keeps the familiar Windows desktop layout. Check the current package notes for runtime requirements. Differences in the interface don’t mean you need to buy a different server or that the protocol has changed. Compatibility still depends on the core in use and the server settings.
Install or extract the download according to its package format. Put an extracted package in a permanent folder with a short path that your account can write to, and keep the application, core, and included files together. If the first launch reports a missing runtime, note the exact component and architecture it requires, then install it through the normal Windows software installation process. Don’t download random files with matching DLL names and drop them into the application folder.
If startup fails, first determine whether the window won’t open or opens but the core fails to start. For the first case, check the runtime, whether the package was fully extracted, and Windows security history. For the second, check the client logs for a missing core, failed configuration generation, or a port conflict. If security software quarantined a file, verify its source and review the specific detection. Don’t disable your entire security suite for convenience.
Import a subscription and check the local listener
Open the subscription group settings, create a group with a recognizable name, and paste the full subscription URL. Saving adds the URL but doesn’t fetch the servers—you’ll also need to update the subscription. When the update completes, return to the server list and select an entry as the active server. If the list is empty, check the update log, group filters, and whether the URL was truncated. There’s no point repeatedly clicking Connect when no server entries are available.
Next, check the local listening port and listener type in the settings. The HTTP, SOCKS, and mixed listener options may vary with core settings. If you’re entering proxy details manually in an app, choose the matching protocol. Use the port shown in the client instead of copying a value from someone else’s screenshot. For local use, keep the listener bound to the loopback address. LAN sharing isn’t necessary for your first connection.
Find the system proxy option in the status bar or tray menu and select “Set system proxy.” This lets apps that follow the Windows system proxy use the local listener, but it doesn’t force every program to use it. First, open a known reachable destination in a browser, then check the client logs for the connection. If the browser works but another app doesn’t, check whether that app follows the system proxy.
TUN, permissions, and restoring settings on exit
Consider TUN only if you need to capture traffic from apps that don’t use the system proxy. TUN uses a virtual network interface and routing, and usually requires administrator privileges, depending on the package and how it runs. Close other VPNs, verify that the regular proxy works, then grant elevated privileges as prompted by the client. If all network access fails after enabling TUN, turn it off first. Then check whether the network recovers and review DNS and routing.
Port conflicts are a common cause of startup problems on Windows. First close any duplicate client instances, then check the specific port mentioned in the logs. You can run the command below in a terminal, replacing the port with the value shown in Settings. This only identifies what is using the port. Use the PID to identify the program in Task Manager; don’t terminate an unfamiliar system process.
netstat -ano | findstr LISTENING
Closing the window doesn’t necessarily quit the client; it may still be running in the system tray. Before quitting, select “Clear system proxy,” disable TUN, and then exit the client. If the program stops unexpectedly, Windows may still point to a local proxy that is no longer running, leaving your browser unable to open any sites. If internet access returns after restoring the system proxy, a leftover setting is likely the problem—not an expired subscription.
Before enabling startup on boot, test several full start, connect, and quit cycles manually. Network access may not be ready immediately after sign-in, so a failed subscription update doesn’t necessarily mean the URL is invalid. Retry later and check the logs. Before upgrading or switching between the desktop and WPF builds, quit the old instance to prevent the two programs from competing for the same port and system proxy.
macOS installation and network permissions
Choose a package for your chip and complete first launch
Check the chip under About This Mac. If it shows Apple silicon, choose the arm64 package for Apple Silicon; if it shows an Intel processor, choose the x64 package. Then get v2rayN from the macOS download page. Prefer a package that matches your Mac’s architecture rather than relying on a compatibility layer for everyday use.
Open the disk image, copy the app to Applications, and launch it from there. Don’t keep running the copy inside the disk image: unmounting the image, moving files, or upgrading can make it hard to tell which copy is actually running. If macOS blocks the first launch, verify where the file came from, then check the relevant prompt under Privacy & Security in System Settings and follow the provided confirmation steps.
Don’t disable macOS security just to bypass a one-time prompt. Handle architecture, file integrity, and permissions separately: choose a compatible package, copy the app again if the transfer was incomplete, and check whether your account can access the application and data folders. If your Mac is managed by an organization, network settings may be restricted by policy. Reinstalling the client repeatedly usually won’t fix that.
Import a subscription and check the current network service
After launching v2rayN, add the URL under subscription group settings, save it, and update the subscription. Before selecting an active server, check that the security method, transport, and required fields from the subscription were recognized. Content with client-specific extensions may not work with every client. If an entry imports but the core reports an invalid parameter, check the field named in the logs instead of enabling every optional setting.
Use the system proxy for your first connection. macOS proxy settings are tied to network services, so Wi-Fi, Ethernet, and other interfaces may each have their own configuration. After setting the proxy, check its status in the details for the network service you’re currently using. If the result changes after switching from Ethernet to Wi-Fi, check the new service’s proxy settings before blaming the server or subscription.
Browsers may use their own extensions or proxy settings, and terminal tools don’t always follow the system proxy. For a reliable test, use an app that follows system settings and check whether its connection appears in the logs. A failed terminal request doesn’t automatically mean the system proxy is broken. If the tool supports a manual proxy, enter the local address and matching listener port in its expected format.
TUN permissions, sleep, and upgrades
TUN uses a virtual interface and system routes. The authorization process depends on the client package, so enable it only after verifying that the basic proxy works. When macOS prompts for administrator approval, make sure the request came from the client you just launched. Don’t use an untrusted terminal script as a universal fix, and don’t run all your everyday apps with elevated privileges.
After waking from sleep, switching hotspots, or changing networks, existing connections may remain stuck. Confirm the new network is working, then reconnect. If needed, turn TUN off and back on to rebuild the interface and routes. If only one network causes problems, keep the other settings unchanged and compare logs across both networks. Focus on DNS resolution and the handshake rather than rebuilding the entire configuration right away.
Before upgrading, export any configuration you want to keep and note where the current user data is stored. Replacing the app doesn’t always remove user settings, so it’s normal to see old preferences after an upgrade. Likewise, moving an app to the Trash may not undo network traffic-capture settings. Before uninstalling or switching clients, disable TUN, restore the system proxy, quit the app, and check the proxy settings for the active network service.
If the client reports a working connection but a managed browser still can’t access the internet, check whether browser policies, extensions, or system profiles specify a different proxy. Their settings may take precedence over ordinary user settings. Note the policy source and contact your device administrator. Don’t try deleting unfamiliar configuration profiles; that could affect work network access or other managed apps.
Linux installation and desktop environments
Check the package format, architecture, and dependencies
On Linux, start with your distribution’s package system, then check the machine architecture. Debian and Ubuntu systems typically use deb packages, while Fedora and other rpm-based systems use the matching rpm package. Don’t try to install a package from a different format as if it were native to your distribution. Choose v2rayN on the Linux download page, and match x64 or arm64 to your machine’s architecture.
These commands only read system information. The first checks the architecture; the second shows the distribution ID. Commonly, x86_64 corresponds to x64 and aarch64 to arm64. The distribution name alone doesn’t guarantee that dependencies are available. Also check the OS version, desktop components, and package manager’s dependency report. A matching file extension doesn’t necessarily mean the package can be installed.
uname -m
cat /etc/os-release
Use your distribution’s software installer or package manager to handle dependencies and keep an uninstall record. If a dependency is missing, save the full error and check your software sources and supported OS versions. Don’t copy shared libraries from another distribution at random. A graphical client also needs a working desktop session; a server with only a terminal isn’t covered by this graphical installation guide.
Import and test from a regular desktop session
After installation, launch the app from the application menu and save its settings as your regular desktop user. Launching the graphical interface as root can save settings to a different user directory, making them seem to disappear when you start the app normally. If that happens, check the user account and data path before importing the same subscription again. Use the client’s supported authorization method for network operations that need elevated privileges, separately from everyday configuration.
The subscription steps are the same: create a group, enter the URL, save it, update the subscription, and select an active server. After the update, check that the core starts before configuring the desktop proxy. Proxy settings vary across Linux desktop environments. Some apps use desktop settings, others read environment variables, and some accept only app-specific options. Turning on the system proxy doesn’t mean every program is using it.
Test with an app that you know follows the desktop proxy, then configure other tools separately. Don’t add proxy environment variables to every shell startup file before checking that the listener works; new terminals could keep pointing to a port that isn’t running. If you’ve set HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY, check both uppercase and lowercase variants as well as each app’s own settings.
TUN, DNS, and network management tools
Before enabling TUN, confirm that the system supports the required virtual network interface and review any permissions errors in the client logs. Some environments also rely on a privilege helper or network management tool. Don’t make the entire configuration folder writable by every user to fix a permissions error. First determine whether the issue is with executing the program, accessing the data folder, or the system privileges needed to create an interface and routes.
Linux systems may run a desktop network manager, a system resolver, container networking, and other VPNs at the same time. If domain lookups fail only when TUN is enabled, but work again on the regular network, check which component is handling DNS. Don’t overwrite the system resolver file straight away: a service may generate it automatically, and your changes could be replaced immediately, making the issue hard to reproduce.
Use the command below to check local listeners and confirm whether the client’s port is open. A listener only means the local endpoint is available; it doesn’t confirm that the remote handshake succeeded. If you can’t see process names due to permissions, you can still check the address and port. Elevate privileges only if you need more detail and according to your system’s administration practices; there’s no need to run the entire client as root just for this check.
ss -lntp
Restore the desktop proxy and disable TUN before quitting. If problems remain, check for another client instance, persistent environment variables, or rules left by another network service before restarting services. After an upgrade, retest the tray, background operation, and startup behavior. Desktop sessions may handle background apps differently, so a closed window doesn’t tell you whether the client is still running.
Android installation and VPN permission
Choose v2rayNG or v2flyNG
Open the Android download page. Start with v2rayNG, which uses the Xray core; choose v2flyNG if your connection details specifically require the V2Fly core. Similar names don’t mean both clients support the same extended parameters. For configurations involving REALITY, check the core’s capabilities and the server requirements. Don’t try to make unsupported fields work by repeatedly switching settings.
Most recent mainstream devices support arm64, but check the processor and the application architectures supported by your device. If the installer reports an architecture mismatch, check whether you need a universal package. After downloading, open the package from the system file browser. If Android asks you to allow installs from this source, grant permission only to the browser or file manager you’re using for this installation, then revoke it afterward if you prefer.
If an update reports a signature mismatch, don’t uninstall the existing app right away. Export the configuration you need and check that the old app and new package came from the same distribution channel and have the same app identity and signing certificate. Uninstalling usually removes app data, including subscription groups and manual settings. You can’t assume one client can be installed over another as a way to migrate; use the import and export options they actually support.
Import a subscription and grant VPN access
Add a name and URL under subscription group settings, save, then return to the main screen and update the subscription. Some versions offer separate options to update through the current proxy or connect directly. Before your first connection, choose a direct update if the subscription URL is accessible without a proxy. If it requires an existing connection, you’ll need a working configuration first; an empty group can’t establish a connection by itself.
When server entries appear, select an active server and start the connection. The first time, Android will ask for permission to create a VPN connection. Approve it to let the client use Android’s VPN interface to capture traffic from selected apps. A VPN icon only confirms that the interface is up—not that the remote server is reachable. Check the logs and try accessing a site in an app. Repeatedly tapping a server won’t grant access if you haven’t approved the prompt.
The Android client’s traffic-capture method isn’t the same as the desktop “Set system proxy” option. App-level proxy settings may let you choose which apps use or bypass the VPN. The meaning of the app list can change depending on the mode, so read the current instructions before enabling it. For your first test, keep the default selection. Once connected, exclude apps one at a time so you don’t accidentally exclude the browser you’re using to test.
Background restrictions, network changes, and sharing
If the connection stops after running for a while, check battery optimization, background activity restrictions, and battery saver. Settings vary by device manufacturer; check the battery and background permissions on the app info page. Change only options relevant to this client, then compare the logs before and after locking the screen. Don’t assume every disconnect is caused by background restrictions. If the process is still running but the handshake keeps failing, check the remote settings.
When switching between Wi-Fi and mobile data, the local interface may remain up even though existing connections have stopped working. Wait until the new network is fully available, then reconnect to the active server. If only mobile data fails, keep the server and routing unchanged while comparing DNS resolution, IPv4 and IPv6 reachability, and handshake errors. Don’t change the transport and security settings at the same time; otherwise, you won’t know which change mattered.
“Allow connections from the LAN” is a separate option. It exposes the local proxy listener to other devices; it isn’t required for the phone itself to connect. If you enable it, consider the listening address, port, and whether the network is trusted. Whether a phone’s hotspot routes other devices’ traffic through the VPN depends on the Android implementation. A working connection on the phone doesn’t mean hotspot devices will use it too.
To disconnect, stop the connection in the client first and confirm that Android’s VPN status has cleared. If Always-on VPN or blocking connections without a VPN is enabled, Android may block network access after the client stops. Check these system settings in the VPN details. For a concise walkthrough of subscription setup, see the Android subscription import guide.
Organize subscriptions and check connection settings
Treat subscription updates and server connections as separate steps
A subscription URL is where the client gets server details. Updating successfully means the client fetched and parsed the subscription this time; it doesn’t guarantee every server in it is currently available. Likewise, a successful connection doesn’t mean the subscription URL will always remain accessible. These are separate stages. When troubleshooting, identify whether the failure occurred while fetching the subscription, parsing its contents, starting the core, or connecting to a remote server. Don’t lump every issue under “import failed.”
Create a separate group for each source, and name it by purpose or source. Don’t put the full URL in the group name. When pasting the URL, check for leading or trailing spaces, line breaks, and punctuation added by the copy tool. Keep the full URL, including query parameters. If the URL has expired, access has changed, or the source returns a webpage, the client may receive something other than subscription data. The update log will be more useful than the server list.
Being able to open a page in a browser doesn’t mean it contains configuration the client can read. A subscription may return different content depending on how it’s accessed, or require an active account. Don’t use the address of a login or sharing page as a subscription URL. If the provider offers multiple formats, choose one supported by your client rather than combining subscription text from multiple sources into one file.
Check connection and security settings one by one
When entering a configuration manually, check the protocol, server address, port, and user ID first, then verify the transport and security settings. VLESS, VMess, and Trojan use different authentication fields. Don’t enter a password from one type of configuration into the user ID field for another. The transport must also match the server. For WebSocket, preserve the path and Host exactly as provided, including capitalization and leading slashes.
The TLS server name is used for certificate validation and the handshake. It may appear in the interface as SNI or server name. REALITY configurations can also require fields such as a public key, short ID, and fingerprint; fill each one in using the server details. Don’t mistake the public key for a password or replace every hostname with the server IP. If a required field is empty after import, check whether the share format is compatible before filling it in manually.
| Setting | What it does | Common mistake |
|---|---|---|
| Server address | Specifies the remote connection target | Pasting the entire share link into the address field |
| Port | Selects the remote service endpoint | Using the local listening port by mistake |
| SNI | Used during the TLS handshake and certificate validation | Changing it to a domain unrelated to the certificate |
| Transport path | Matches the relevant transport service | Missing a slash or leaving extra spaces |
Share links and subscription data may contain encoded parameters that are easy to break when edited as plain text. Whenever possible, make changes in a client-supported form and keep an export of the original first. For an overview of the protocols, see the VLESS setup guide and REALITY settings guide. Use the values provided by your server, not example values.
What subscription updates, filters, and backups can and can’t do
An update may overwrite server entries managed by the subscription, so don’t rely on a temporary manual edit as a permanent change. To keep custom entries, move them to a separate group or export a backup using the client’s supported options. If your current selection stops working after an update, the remote source may have removed or renamed that entry. Select an active server again before deciding there’s a connection problem.
Filters can hide entries, so an empty list doesn’t necessarily mean the subscription returned nothing. Switch to all groups, temporarily clear keyword filters, and check the update log. When removing duplicates, don’t rely on display names alone; entries with the same name may have different ports, transports, or authentication details. For organization tips, see the subscription groups and server filtering notes. Export a recoverable backup before making bulk changes.
Store configuration backups somewhere secure, separate from public screenshots and support requests. An export may include server credentials and subscription URLs; changing the display name doesn’t remove sensitive data. After restoring to another device, recheck local ports, system proxy settings, file paths, and permissions. These device-specific settings can’t necessarily be carried over from an old backup unchanged.
System proxy, TUN, and routing
Understand how traffic is captured before choosing a mode
The system proxy, TUN, and routing rules operate at different layers. The system proxy tells apps that follow it to send requests to a local port. TUN captures network traffic through a virtual interface. Routing rules decide which outbound route a connection uses after it reaches the core. Even a complete set of routing rules can’t proxy an app whose traffic never enters the client. That’s the first distinction to make when troubleshooting.
For everyday desktop browsing, start with the system proxy. Once you’ve confirmed that pages load and the corresponding connections appear in the logs, consider whether you need broader traffic capture. Some apps have their own proxy settings, where you can enter the local listener directly. TUN covers more traffic, but adds network interfaces, routes, DNS, and permissions to the mix. It isn’t always the right first step, and it can’t fix incorrect server settings.
“Global” usually describes how traffic that has already entered the client chooses an outbound route. It doesn’t guarantee that every connection on the device is captured. With the system proxy enabled, an app that ignores it may still connect directly, even if global routing is selected. Conversely, TUN can use routing rules to send some destinations directly. To determine where traffic goes, check the capture method, matching rules, and actual outbound logs together.
Routing order and DNS
Rules are usually evaluated in order, but exact behavior depends on the core. Put specific exceptions before broader rules and note the purpose of each rule. After adding one, test it with a clearly identified destination instead of importing several overlapping rule sets at once. Domain rules and IP rules aren’t interchangeable: the available match depends on whether the domain is known when the connection reaches the core.
This Xray routing object is an example of routing private IP ranges through an outbound tag named direct. It must be part of a complete configuration, and that outbound tag must already exist; it isn’t a standalone client configuration. A graphical client may generate its configuration automatically, so direct edits to generated files are likely to be overwritten. Use the routing settings in the interface whenever possible.
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"ip": ["geoip:private"],
"outboundTag": "direct"
}
]
}
}
Where DNS resolution happens can affect the result. An app resolving a domain to an IP address before connecting is a different path from passing the domain to the proxy for resolution. TUN may also capture DNS, so changing browser settings alone doesn’t prove that DNS resolution has changed. If a domain fails but its IP is reachable, check the actual DNS path and logs. Don’t replace every DNS server at once; change one part at a time so you can compare results.
LAN sharing and access controls
Before sharing with other devices, confirm the computer itself connects successfully, then enable “Allow connections from the LAN” or the equivalent listener setting. Other devices need the computer’s current LAN address and local proxy port—not the remote server address or 127.0.0.1. A loopback address always refers to the device it’s entered on, so entering it on a phone makes the phone look for a service running on itself.
Devices on the same Wi-Fi network can still be isolated from each other. Guest networks, wireless client isolation, and system firewalls may block access. Check the devices’ network ranges and network profile, then allow only the required app or port. Limit the listener to a trusted network, and enable authentication if the client supports it. Don’t expose your local proxy to the public internet through a router just to test it.
Check that the receiving device supports the proxy type you’re sharing. If its settings accept only HTTP, you can’t enter a SOCKS-only port. Some device proxy settings apply to only certain apps. When you’re done sharing, turn off the LAN listener and remove the proxy address from other devices. For device-side setup steps, see the v2rayN LAN sharing guide. Troubleshoot sharing separately from connection issues between your computer and the remote server.
Common setup questions and connection troubleshooting
Gather evidence for the stage where the failure occurs
First, define the problem: can’t update the subscription, can’t start the core, failure in every app, or failure in just one app or destination? Note what changed since the last time it worked and which traffic-capture method is active. Keep the test app and destination fixed while troubleshooting. If you change networks, servers, and DNS all at once, you won’t be able to reproduce the original error or identify its cause.
A normal-looking client window doesn’t mean the core is working. Check the logs for messages confirming that the configuration loaded and the local listener started, then find the earliest error. A port conflict, unsupported configuration field, missing data file, and remote timeout are different problems. Fix local startup issues first rather than immediately replacing the subscription. Once the local listener works, check the remote connection and whether the app is sending traffic through the proxy.
Keep the log window focused: note when the test starts, make one request, then inspect the entries around that time. Large amounts of unrelated history can hide the first useful error. If you temporarily increase log verbosity, return it to your normal level when you’re done troubleshooting. Before sharing logs, remove subscription URLs, user IDs, and authentication details. Keep only the error type, the stage where it occurred, and relevant environment details.
Timeouts, connection refusals, and certificate errors
“Connection refused” often means no service accepted the connection at that address and port, but it can also be returned by an intermediate network device. A timeout means the expected response didn’t arrive in time and can have more causes. First check the remote address and port, then see which destination the client actually tried to reach in its logs. If it fails on only one network, test on another without changing the configuration instead of switching protocols immediately.
For a TLS certificate or handshake error, first check the system date, time, and time zone. Then compare the SNI, server address, security type, and transport settings with the server details. Incorrect DNS resolution can also send you to a host with a mismatched certificate. Disabling certificate verification won’t fix these settings and weakens authentication. Don’t use it as a routine workaround or save it as a default.
If the core doesn’t recognize a configuration field, check whether you imported a format intended for a different core or selected an unsuitable core in the client. Updating the client and switching cores are separate actions; neither is guaranteed to resolve every compatibility issue. Identify the required capability from the error before choosing a client. For background on the cores, see Xray vs. V2Fly: choosing a core. For handshake problems, see the TLS and certificate troubleshooting notes.
Restore a basic test setup and retest one change at a time
If a browser works but another app doesn’t, check whether the app follows the system proxy, has its own proxy settings, or is excluded by per-app rules. If only certain destinations fail, check routing matches, DNS resolution, and the destination itself rather than reinstalling the entire client. If TUN fails while the system proxy works, focus on the virtual interface, DNS capture, routing conflicts, and permissions. Don’t start by re-entering server credentials.
Before rolling back, export the current configuration. Disable custom routes and extra DNS settings, turn off TUN, and test the system proxy with one known active server. On Android, restore the default per-app selection and grant VPN permission again. Change one setting at a time and note the result. Once the basic setup works, re-enable features in their original order to find the setting that first caused the problem.
If regular internet access is still broken after quitting the client, restore the system proxy, check any Always-on VPN policy, and make sure no other program is capturing traffic. Once the network is back, start the client and observe the local listener and remote handshake. If you need help, include your operating system and architecture, client name, capture method, a redacted error message, and the steps you’ve tried. That’s more useful than a screenshot saying “Unable to connect” and avoids repeating checks you’ve already done.
The subscription updated, but servers still won’t connect. What should I check?
A successful update confirms that the subscription was fetched and parsed. Select an active server, check that the core and local listener are working, and confirm that the request reaches the client. Then use the logs to check the remote address, transport, and security settings.
Which settings should I restore after testing?
Clear the system proxy set by the client, stop TUN or VPN, turn off temporary LAN sharing, and restore any app proxy settings or environment variables changed during testing. Verify that regular internet access works, then decide which settings you want to keep for everyday use.