V2Ray Setup Guide
for All Platforms

Before You Begin: Check Your Configuration and Connection Path

Understand the Client, Core, and Server Configuration

Start by separating the setup into three parts. The graphical client manages servers, subscriptions, routing, and system integration. The core handles connections and traffic forwarding. The server configuration provides the remote address, port, protocol, and authentication details. Installing a client does not provide a working connection, and importing a configuration does not guarantee the remote server is online. Check each part separately to avoid repeatedly changing system proxy settings when the address is wrong, or assuming the core is working just because the interface opened.

For Desktop platforms, start with v2rayN; for Android, consider v2rayNG. Use v2flyNG when you need V2Fly core configuration. These clients differ in interface and configuration support. If a client recognizes a share link, that only means it can parse the syntax; it does not mean every transport option is supported. Check the server's protocol, transport, and core requirements before choosing a client. Don't remove unfamiliar fields just to make an import succeed.

Check your OS version, processor architecture, and package type. System settings can usually show your processor and OS details; choose the architecture for the environment actually running on the device, not just its brand. Desktop installers, disk images, and Linux packages have different installation steps. For Android, a universal package and an architecture-specific package aren't interchangeable based on file size alone. Choose your platform on the client downloads page, read the architecture notes on the download card, then install.

Prepare Your Subscription and Record Existing Network Settings

Get a valid subscription URL or individual share link. A subscription usually provides a server list that can be refreshed; a share link describes a single connection, and the import options may differ. When copying, check for extra spaces, quotation marks, or line breaks. Don't copy the webpage title along with the link. Treat subscription URLs as passwords: they may contain personal access credentials. Never include the full URL in screenshots, logs, or public support requests, and don't use someone else's configuration for testing.

Note any existing proxy, other tunneling tools, and manual DNS settings so you can restore them later. For your first setup, enable just one connection method: verify a browser with the system proxy first, then try TUN if needed. Running multiple clients at once can cause port conflicts, overwrite system proxy settings, or create routing loops. Work- or school-managed devices may restrict network extensions or administrator access. If a policy blocks installation, check what you're authorized to do; don't bypass security controls.

Build a Minimal Working Test Setup

Before testing, check your system date and time zone. Encrypted connections may rely on certificate validity, and an incorrect clock can cause handshake failures. Confirm that your local network works and that your browser has no separate proxy extension enabled. Pick a known-reachable test site as a baseline and keep the test conditions consistent. The client's connectivity test, browser requests, and traffic from other apps may use different paths, so one result can't stand in for all the others.

Check the local listening address and port. On a personal device, listening on the loopback address is usually enough. Allowing LAN connections expands access; it isn't a general fix for connection failures. A mixed port can accept proxy requests supported by the client through a single entry point, but its exact behavior depends on the settings. The 10808 shown here is only a common example. Check your current settings instead of copying it and assuming the port is listening.

Save your first working setup as a baseline. Record the client, connection method, routing preset, and local port; there's no need to record sensitive credentials. When changing DNS, the core, or TUN later, change one setting at a time and retest on the same network. That way, you can revert to the previous state instead of guessing which of several changes caused the issue. If you just need to connect for the first time, return to the quick-start guide and follow the steps for preparation, import, mode selection, and verification.

Windows: Installation and System Proxy Setup

Choose the Desktop or WPF Edition

Open the Windows downloads and choose the Desktop or classic WPF edition from the v2rayN card. The Desktop edition uses a cross-platform interface; WPF is designed for Windows. Their layouts, settings, and runtime requirements may differ, so don't assume that screenshots or button locations match between editions. Read the package notes and check that your OS and architecture are supported. For a comparison, see Desktop vs. WPF: Which Edition Should You Choose?

Follow the installer prompts to install the program. If you have a compressed distribution, extract it fully to a separate directory where you have write access, then launch it. Don't run the app from an archive preview or mix program and core files from different packages. Leave room for configuration files and avoid temporary directories that may be cleaned automatically. If the app reports a missing runtime dependency on first launch, follow the package instructions; don't download a same-named system file from an unknown source and overwrite it.

After launch, check the main window log to make sure the core hasn't exited immediately. Closing the window may leave the app running in the system tray, so check there before launching it again to avoid a second instance. If the installation directory contains personal files, export your configuration and keep the old directory before upgrading. Don't overwrite files while the client is running, or copy only the executable and leave out resources from the same package. After upgrading, verify the listening port and system proxy again.

Import a Subscription and Enable One Proxy Entry Point

In subscription settings, create a group, enter a recognizable name and the subscription URL, save it, then update the group. For an individual share link, use the corresponding import-from-clipboard option. Check that the expected servers appear, select one, and set it as the active server. Importing updates the configuration list but may not switch the server currently in use. For help finding the relevant controls, see the v2rayN main window guide.

For your first test, enable automatic system proxy configuration and leave TUN off. The system proxy sets a local proxy address in your OS settings, but only apps that follow those settings will use it. A browser is usually a good first test; games, updaters, and apps with their own network settings may not follow the system proxy. If your browser has a proxy extension, disable it before testing. For manual app setup, use the loopback address and port the client actually listens on, and select the matching proxy type.

Try TUN only if you need to route traffic from more apps. It uses a virtual network interface and routing to capture traffic, and typically requires administrator privileges; exact requirements depend on the client and OS. Clear the system proxy first, then enable TUN as prompted and check the logs for permission, interface creation, or routing errors. Keep the core running and confirm the active server hasn't changed. TUN isn't suitable for every network, and other tunnels, virtual adapters, or management policies may conflict with it.

Fix Port Conflicts and Loss of Connectivity After Exiting

If listening fails, check whether the error explicitly says the address is already in use. The commands below only diagnose local ports; they don't terminate processes. The example checks 10808; replace it with the value in your current settings. The last output column shows the process ID, which you can look up in Task Manager. Identify the program before closing a duplicate instance or changing the port. Never terminate a system process based on its port number alone.

netstat -ano | findstr :10808

After changing the port, update any apps you configured manually. If you use automatic system proxy settings, apply them again and make sure the OS isn't still pointing to the old port. For a fuller walkthrough, see How to Fix a Local Port Conflict. Respond to firewall prompts based on how you plan to use the app. If you only need it on your device, there's no need to enable LAN listening just for a test or disable your entire firewall instead of troubleshooting the specific issue.

Before exiting the client, clear the system proxy, turn off TUN, then exit normally. If the app crashes and your browser loses connectivity, open the system proxy settings and check for a leftover loopback proxy address. Once the client is stopped, clear it and test your direct connection. If a problem starts after waking from sleep or switching Wi-Fi networks, reconnect to the current server and reapply the connection method. Reinstalling won't necessarily remove stale system-level proxy settings.

macOS: Choose the Right Chip and Grant Network Permissions

Choose the Right Chip and Launch the App

Open the macOS downloads and choose the v2rayN build that matches the chip shown in About This Mac. Apple Silicon uses arm64; Intel uses x64. Don't guess based on the device's appearance or purchase year, and don't assume compatibility layers solve every network extension issue. Once downloaded, open the disk image and move the app to Applications as directed by the package. Launch it from there instead of relying on a copy inside a mounted image.

The first time you open the app, macOS may ask you to confirm that it was downloaded from the internet. Verify the file's source and app name, then follow the prompt in System Settings for that app. Don't disable security checks globally just to open one program, and don't run commands from unknown sources to remove restrictions. If the OS version or architecture isn't supported, return to the download notes and choose a compatible build rather than repeatedly changing file permissions. Don't troubleshoot subscriptions or DNS until the app launches successfully.

Make sure the app can save settings and retains them after you reopen it before continuing with imports. The Applications folder and your user configuration folder serve different purposes. Before upgrading, use the client's backup or export feature; keeping the app icon alone doesn't mean the configuration is saved. System backups offer another recovery option, but after restoring a client configuration, check local ports, permissions, and network interfaces, which may differ on the new device.

Import a Configuration and Check the System Proxy

Add the URL in subscription settings, save and update it, then select an active server and check the runtime log. For an individual share link, make sure the contents are complete and use the clipboard import option. Links from other desktop platforms may work as input, but don't copy an entire generated configuration as a substitute for local settings. If the configuration includes certificate paths, script paths, or interface names that exist only on the original machine, reset them in the interface instead of leaving stale paths in place.

Start by using the system proxy to test a browser. On macOS, proxy settings are tied to network services, so check the service you're currently using, whether Wi-Fi or Ethernet. If the browser doesn't use the proxy after automatic setup, open Network settings and check the proxy options for the active service. Confirm the address points to your device and the port matches the client. Check again after switching network services; an enabled proxy for an inactive service doesn't mean your current connection is using it.

Command-line tools and apps with their own proxy settings may not follow the system proxy. To test them separately, specify the proxy entry point explicitly and compare the app's behavior with the system settings. The command below applies when the current mixed entry point accepts HTTP proxy requests. It tests a single request through the local entry point without changing system proxy settings. A response means the request completed, but you'll still need routing logs and an exit check to confirm it used the expected remote route.

curl -I --proxy http://127.0.0.1:10808 https://example.com

Enable TUN and Handle Network Changes

If you need TUN, first record a working system proxy setup, clear the system proxy, then enable TUN. Grant the permissions requested by the client; the prompt varies by OS and package. If the log reports an operation not permitted, virtual interface creation failure, or a routing error, check that permission was granted before changing remote protocol settings. TUN controls how traffic enters the client; it can't fix an incorrect server address, authentication details, or transport.

When using another tunnel at the same time, pay close attention to the default route and which tool controls DNS. For testing, leave only one client managing network traffic to avoid competing changes to settings. After joining a company network, hotspot, or public Wi-Fi, you may need to complete that network's sign-in flow before reconnecting the proxy. If direct access also fails, troubleshoot the underlying network first; changing servers repeatedly won't open a network login page.

If only some sites fail after waking from sleep, reconnect first and check for DNS errors or stale routing. Don't immediately reset all network settings. You can exit the client, confirm the system proxy has been restored, test direct access, then enable one connection method again. Manual DNS, browser Secure DNS, and the core's DNS are separate layers. Having several custom resolvers makes it harder to trace requests, so check each layer in the routing section of this guide.

To exit normally, stop TUN, clear the system proxy, then quit the app. Do the same before uninstalling; removing the app doesn't automatically clear every network setting. If you still can't connect after quitting, check whether the proxy for your active network service points to a stopped local port. Keep a record of a working setup, especially the local port and connection method, to make recovery after an OS update or device change easier.

Linux: Packages and Desktop Proxy Setup

Choose the Package Format and Processor Architecture

Open the Linux downloads, choose the deb or rpm package for your distribution, then check whether your system uses x64 or arm64. You can't identify the package format from the desktop appearance alone; distributions with the same desktop environment may use different package managers. Check your distribution and architecture in system settings first. If you need a read-only check, run the command below. Commonly, x86_64 maps to x64 and aarch64 to arm64.

uname -m

Open the matching package in your distribution's graphical installer and review its dependencies before installing. If dependencies can't be satisfied, check your OS version and software repositories instead of forcing the installation past dependency checks. Once installed, launch the app from the desktop menu and check the window and logs. If the interface appears but the core exits, inspect the core log; don't confuse a rendering issue with a network protocol error.

Keep the user configuration directory owned by your regular account. Don't run the entire graphical client as root just to use a standard proxy; it can create configuration files your regular user can't write. Later, saving settings, updating subscriptions, or writing logs may fail when running as a normal user. If you have changed the account used to run the app, identify affected directories and restore permissions using your distribution's documentation. Don't recursively loosen access controls across your home directory.

Import a Subscription and Separate Desktop Settings from App Settings

Subscription import works much like it does on other desktop platforms: create a group, enter the URL, save, update, then select an active server. If an update fails, first check whether the request needs to use an existing proxy. Don't change the subscription URL and network mode at the same time. When migrating from another device, use the client's share-link or export feature where possible; recreate settings that depend on local paths. Configure the app's proxy entry only after the core starts, so the app doesn't keep connecting to a port that's not listening.

System proxy support on Linux depends on the desktop environment and the app. Some apps read desktop proxy settings, others use environment variables, and some only use their own settings. Seeing that the client set a system proxy doesn't mean every program uses it. Test with a browser first, then check other apps individually. If the tray icon is missing, don't assume the app has stopped. Check the window and process state; it may just be a difference in desktop tray integration.

An explicitly proxied request can help isolate problems in the connection layer. The command below requires the local port to accept SOCKS requests. socks5h passes the destination hostname to the proxy entry instead of resolving it locally for this request. This doesn't mean all subsequent DNS lookups will go through the remote server; actual behavior depends on the core's routing and DNS settings. Replace the port before running it. You don't need to add it to global environment settings.

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

Avoid changing system-wide environment files for your first test. Environment variables may only affect newly started processes; a browser that's already running won't inherit new values, and apps launched from a graphical desktop may not read terminal settings. If a command-line app needs a proxy, test it for that app first, then decide whether to make the setting persistent. Don't configure desktop proxy settings, app-level proxies, and global environment variables all at once and assume one working app proves the whole setup is correct.

Check TUN Permissions and Listening Status

TUN needs access to virtual interfaces and routing controls. How to enable it depends on the distribution, kernel, and client package. Follow the current client's authorization prompts rather than copying permission steps from another OS. Before enabling TUN, stop other tools that manage routes; afterward, check that the interface was created and rules were applied. If the UI shows TUN enabled but the log reports insufficient permissions, traffic may not be entering TUN at all. Changing servers won't fix a permissions problem.

If the local entry point isn't reachable, use ss -lntp to check listening TCP ports; which process details are visible depends on your permissions. If the expected port isn't listed, check whether the core exited and whether the configuration loaded. If another process is using the port, confirm what it does before closing a duplicate instance or changing the listening port. For remote connection failures, check DNS, authentication, and transport logs. Don't expose the port on every interface to work around a remote error.

After switching networks, waking from sleep, or exiting the client, check for leftover desktop proxy settings. Uninstalling the package won't necessarily restore proxy settings you've configured manually, and terminal environment variables need to be removed separately. Limit changes to settings you can clearly restore, and record them before you proceed. After testing, verify the browser, required apps, and direct connection separately. Setup is complete when all three behave as expected.

Android: Installation, Permissions, and Background Operation

Choose a Client and Install the Right Architecture

Open the Android downloads. Start with v2rayNG, which uses the Xray core; use v2flyNG when you need V2Fly core configuration. Most newer devices use arm64, but check the architectures supported by your device. If you're unsure, consider a universal package rather than installing several architecture-specific packages at random. Installation failures may result from the OS version, architecture, or a signature conflict with an existing app; troubleshoot each cause separately.

When you open an installer from a browser or file manager, Android may ask you to allow app installs from that source. This permission usually applies to the app you're using to open the file; you can revoke it after installation if you prefer. If Android reports a conflict with an installed app, check its source and export its configuration before removing it. Each client has separate app data; installing another client won't carry over your subscriptions, servers, or routing settings.

On first launch, review any notifications and network prompts before opening subscription settings. Android clients use the system VPN service to create a traffic entry point. Granting this permission doesn't mean you're connected to a remote server; it only allows the app to create a network tunnel. You still need a valid configuration and a working core. If your device is managed by a work profile or policy, VPN services may be restricted. Check the management requirements instead of reinstalling the same package.

Import a Subscription and Check Which Apps Are Routed

In subscription settings, create a group, enter a name and subscription URL, save it, then update. If you have an individual share link, use the clipboard import option. Camera permission is only needed if you use a feature that scans configurations. After import, check that the server name, protocol, and transport settings are complete, then select a configuration and connect. Don't keep importing an expired subscription URL as an individual share link: the two import options handle different content, and retrying won't make the URL valid.

Tap Connect, read the system VPN permission prompt, and confirm. Check the persistent notification and client logs to make sure the service hasn't stopped immediately. Android generally allows only one active VPN service in the same user profile, so another network tool may replace the current connection. For testing, stop other VPN-based tools, especially traffic-filtering apps. The VPN indicator only shows that a tunnel was established; test an actual request to verify the remote connection and routing.

Check per-app proxy settings. With an allowlist enabled, apps not selected may bypass the proxy; with a blocklist or exclusion list, listed apps may connect directly. These settings have opposite meanings, so check what the list mode does rather than just whether an app appears in it. For a baseline, test a browser with the default app scope, then add the apps you need one at a time. Browser Secure DNS, caching, and reused connections can affect results. After changing rules, start a new request instead of only refreshing an open page.

Balance Background Operation and Battery Use

If the connection drops when the screen turns off, first determine whether Android stopped the service or the service is still running while requests fail. For a stopped service, check battery optimization, background activity, and autostart restrictions. If it keeps running, inspect the logs, network, and server status instead. Settings vary by device manufacturer, so look for the equivalent options on your device. Don't disable every background restriction at once; change one that directly affects the app, then check what happens after the screen turns off and on.

The persistent notification indicates service status. If it disappears, that doesn't by itself prove the service stopped, but it can help narrow down the problem. For ongoing connections, keep a notification that clearly shows connection status. High battery use may be caused by frequent connectivity checks, repeated reconnections, overly verbose logging, or constant background traffic. Exempting the app from battery optimization can help it stay connected, but won't make the core more power-efficient or fix an unstable remote connection.

When switching from Wi-Fi to mobile data, the existing connection may stop working and need to be re-established. If it fails on one network, confirm that the network itself has internet access, then compare the same server and configuration. Public networks may require a sign-in page; mobile data may be restricted by data-saving settings or background data permissions. Don't rebuild all your subscriptions because the first request times out after a network switch. Check the reconnection result and logs first.

When finished, disconnect in the client, then check the system VPN indicator and persistent notification. Stop the current service before switching clients; a change in VPN authorization doesn't indicate a server failure. For more on background limits and battery trade-offs, see v2rayNG Background and Battery Settings. Keep any logs you need before clearing app data: clearing it deletes local configuration and shouldn't be a routine response to every disconnection.

Subscriptions and Migration: Keep Your Configuration Recoverable

Choose the Right Import Method

Subscription URLs, share links, and full configuration files serve different purposes. A subscription URL fetches a server list periodically; a share link transfers the settings for a single connection; a full configuration file may include local inbounds, outbounds, routing, and DNS. A client that supports one format may not accept the others through the same import option. Identify the content before importing. Don't treat an ordinary webpage URL as a subscription or paste a full configuration into a field that only accepts links.

Create clearly named subscription groups based on their source or purpose; don't include credentials in the name. Save the group, update it on its own, then check the results. If the update succeeds but the list is empty, check whether the response was empty, the subscription format is unsupported, or filters are hiding entries. If duplicate names appear after an update, don't delete servers based on their display names alone; names aren't unique identifiers. Check which group and active server are involved before removing old entries.

Distinguish subscription-managed entries from manually added ones. An update may overwrite parameters supplied by the subscription, so changes made directly to a subscription entry may disappear next time. For temporary testing, use the client's duplicate or separate-configuration feature, label it as a test, and keep the original. Don't rely on a temporary workaround as a long-term source. If the remote service changes, update the subscription or confirm the settings with its provider.

Find Out Where a Subscription Update Fails

First check whether the update request was sent. An empty URL, invalid format, or extra copied characters can cause a failure before connecting. DNS resolution errors happen before a connection is established; timeouts, certificate errors, and access denials occur later. Some URLs redirect to a sign-in page or return an error page, so a successful request doesn't guarantee the response is a subscription. Check the status and error summary in the log. Don't lump account expiration, access restrictions, and invalid content together as “the client can't open it.”

The “bypass proxy for subscription updates” option only changes the route used by update requests; it doesn't affect regular app traffic. If the current server is unavailable and updates depend on it, try updating directly. If the subscription URL is only reachable through a proxy, establish a working connection first. Change this setting on its own and compare the results. Don't switch DNS, active servers, and update routing at the same time, or you won't know which change helped.

After updating, check whether the active server is still valid. The remote list may remove an old entry or change its settings, and whether the client automatically switches depends on its implementation. Don't close the window just because it says “Update complete.” Test the current connection and check that group filters aren't hiding new entries. Select a server again if needed. If every entry fails, check the subscription contents, account status, and local network before changing ports one by one.

Migrate Your Configuration and Verify the Restore

Before migrating, use the client's export or backup feature and check what it includes. Some options export only server links; others include subscriptions and UI settings. Don't rely on the filename to tell you what's inside. Record subscription sources and any custom rules separately, and store them somewhere protected. Don't enable LAN sharing for an entire configuration directory just to make migration easier, and don't put credential-bearing files in a public sync folder. Verify that a backup can be restored while the original device is still available.

For cross-platform migration, transfer general server details and subscription URLs first, then reset local ports, system proxy, TUN, and file paths on the destination device. Windows paths and network interface names won't work as-is on Linux or macOS; Android per-app lists don't map to desktop app settings. Different cores may also support different protocol fields. After import, check whether the client ignored any settings. No error message doesn't mean every field migrated correctly.

After restoring, test one server first, then restore routing and DNS, and finally configure automatic updates and background operation. Save a checkpoint after each successful stage so you can roll back. Use the same sequence when upgrading: export, stop the app, upgrade, check the port, and verify a request. Don't delete the old directory without a recoverable backup, or force an entire runtime configuration from an older program into a directory managed by a new interface.

Routing and DNS: Understand the Entry Point, Rules, and Exit

Separate Network Access from Routing Decisions

System proxy and TUN determine how traffic enters the client; routing determines which exit it uses. They're not the same switch. If an app doesn't follow the system proxy, its traffic never reaches the core. With TUN enabled, rules can still send traffic directly. A client's global proxy mode usually means the proxy is the default exit; it doesn't guarantee that every system process is captured. Before interpreting results, confirm the entry point, check the route, then verify that the remote connection succeeded.

Start with a routing preset provided by the client to establish a working baseline. Add only rules you actually need, and pay attention to their order. Rules are commonly evaluated in sequence, so a broad condition near the top can take precedence over a more specific one below. Direct access for LAN addresses can help reach routers, printers, and local services, but coverage depends on the preset. Internal business domains may resolve to private addresses and can't always be handled with public domain lists alone.

Before editing custom rules, define what each rule matches. Domain, destination address, and app conditions are different dimensions and aren't interchangeable. An app connecting directly to an IP address may not match a domain rule. Traffic sniffing can provide additional domain information, but doesn't work for every connection. If a rule doesn't match, check the actual destination, rule order, and default route. Don't clear the entire rule set right away, or you may lose working routing behavior.

Read Rule Examples and Match Them to Real Outbound Tags

The Xray/V2Fly-style routing object below sends LAN addresses direct and routes the example domain and its subdomains through the proxy. It's a syntax example, not a complete configuration to paste into any client text field. Confirm that the current core supports these fields and that the generated configuration includes outbound tags named direct and proxy. If you're using a graphical rule editor, enter the matching conditions there; don't paste the whole object into a field that only accepts domain lists.

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

The private-address rule in this example depends on geographic data resources available to the core; if they're missing, configuration loading may fail. Rule syntax and resource layouts differ between cores and can't be mixed. Keeping the client-generated configuration as read-only troubleshooting material is safer. Direct edits to generated files are often overwritten when settings are saved or the app restarts. After making a change, confirm that the configuration loads, then test rule matching. If the core won't start, fix syntax or resource errors before investigating website access.

Check DNS and Connection Reuse in Layers

DNS lookups may happen in the OS, browser, app, or core. Changing the client's DNS won't automatically override each app's own resolution strategy. Browser Secure DNS and system Private DNS can also change where queries go. First identify which component resolves the destination hostname, then check whether the query follows the expected route. No public DNS address is a universal fix: reachability, latency, and responses vary by network, so verify with an actual request.

Also distinguish resolving the server's hostname from resolving the destination website. Before connecting remotely, the client may need to look up the server address. If that lookup depends on a proxy tunnel that hasn't been established yet, it can create a dependency loop. Client presets often handle this bootstrap step; don't remove it casually when customizing DNS. If connection logs show a resolution timeout, identify whether the failing hostname belongs to the server or the destination site before checking the local network, core DNS, or an app's own resolver.

After changing rules, close the existing connection or restart the test app so connection reuse doesn't hide the change. Browser caches and existing long-lived connections may keep using old results; refreshing a page doesn't always create a new connection. Choose a clear test destination, record the selected exit and failure stage, and keep a direct-connection comparison. Successful routing only confirms that the expected path was selected; the remote service may still reject the request. Separating these conclusions avoids changing rules that are already working.

Common Setup Questions: Troubleshoot by Layer

Start by Identifying the Scope of the Problem

When a connection fails, describe exactly what isn't working: the client won't start, the core exits, a subscription won't update, a browser can't load sites, or only one app fails. Note whether it began after installation, an upgrade, a network switch, or a setting change. A narrower description points to the next check. Don't label every symptom as an unavailable node or clear the configuration first; that can erase the most useful clues about what changed.

Check each layer in order: local network, client core, local entry point, remote connection, and destination request. If direct access fails, fix the underlying network first. If the core exits, check the first error. If no port is listening, address startup and port conflicts. If only one app fails, check its proxy entry and per-app settings. If every destination fails, investigate shared factors such as DNS, authentication, or remote reachability. Test one layer at a time to avoid confusing results by switching several servers and routing rules at once.

A successful client connectivity test and a failing browser aren't contradictory. The test tool may connect directly to the selected server, while the browser may not be using the system proxy or may match a direct route. Conversely, a failed latency test alone doesn't prove that real requests will fail. Retest with the same destination and a clearly defined entry point. If needed, use an explicit proxy command from this guide to isolate connection setup. Base your conclusion on the request path, not a single status icon.

Understand the Failure Stage and Keep Only the Logs You Need

“Connection refused” usually means the address and port didn't accept the connection. The local entry point may not be running, or the remote port may be wrong; check the destination in the log. A “timeout” means a step didn't finish within the allotted time. It can happen during name resolution, connection setup, or the handshake, and doesn't by itself mean the server is offline. Review the relevant log lines around the error to determine whether the failure is local or remote before changing settings.

For a handshake failure, check the system clock, server name, transport settings, and server-side requirements. Don't treat turning off certificate verification as a permanent fix for certificate errors; it changes the connection's security. For authentication failures, re-import a valid configuration rather than manually editing identifiers and introducing further discrepancies. For configuration parse errors, check the field and core compatibility first. For more detail, see Common V2Ray Runtime Log Errors Explained.

If you need more detailed logs temporarily, capture only the short period needed to reproduce the problem, then restore the normal log level. Verbose logging over time uses more storage and resources and may reveal sites you visit. Before asking for help publicly, remove subscription URLs, credentials, personal file paths, and device identifiers. Keep only the error type, failure stage, and relevant settings. Don't upload a full generated configuration or share a complete link to prove there's a problem.

Go to the Relevant Setting for Each Issue

Once the connection works again, record the change that fixed it and undo temporary experiments. If the issue was a port conflict, keep the new port and update the corresponding app settings. If a network switch caused the problem, there's no need to retain DNS and routing changes you tested along the way. To rebuild a minimal setup, return to a single entry point using the proxy mode steps in the guide, then restore only the features you need, one at a time. Keep the final setup clear, reproducible, and easy to roll back.