V2Ray Setup Guide for All Platforms

Before you begin: platform, configuration, and connection method

Know the difference between the client, core, and server configuration

V2Ray is a technology name in the Project V ecosystem. In practice, installation and day-to-day use are handled through graphical clients. For desktop, v2rayN is the recommended choice. On Android, start with v2rayNG, which uses the Xray core; consider v2flyNG if you specifically need the V2Fly core. The client stores configurations, updates subscriptions, and provides the settings interface. The core handles protocols, connections, and routing. Installing a client does not provide a server or create a working subscription. Before you begin, obtain a subscription URL, share link, or complete configuration file from your provider, and confirm which clients it supports.

Configuration compatibility is about more than similar names. Protocols such as VMess, VLESS, and Trojan require their own matching fields, and transport and TLS settings must also align. For configurations with REALITY parameters, confirm that the target core and its specific implementation support the required features; do not casually replace the original security settings with a different option. A configuration appearing in the client only means the importer recognized some of its contents—it does not mean the core accepted every parameter. If a subscription's format is unclear, ask the provider rather than guessing by switching cores repeatedly.

Check your system architecture and installation location

Check your processor architecture in system settings before downloading, then choose the matching installer. The Windows download section distinguishes the desktop edition from the classic WPF edition; macOS downloads are split between Apple Silicon and Intel; Linux packages vary by deb or rpm format and processor architecture; Android packages include arm64 and universal options. A mismatch can prevent installation or cause an error only when the core starts. On desktop, install to a regular directory writable by your user. Do not launch directly from an archive preview, or place the runtime directory in a temporary download cache, a frequently conflicted sync folder, or a read-only location.

Get your network and configuration details ready

First, confirm that your system can access the resources you need without a proxy, and check that the system date and time zone are correct. Save the full subscription URL, paying attention to query parameters, letter case, and trailing characters. Access tokens in URLs are credentials—never post them in public forums. When troubleshooting, note the client name, system architecture, selected core, and time of the error, but do not record the full subscription URL. If you need to share a screenshot, hide server addresses, user IDs, and personal account details first. Before moving from another client, export its configuration and save the backup somewhere you control.

Understand the difference between system proxy, TUN, and VPN

A desktop system proxy tells apps that honor system settings where to find the local proxy, making it a good fit for browsers and typical desktop applications. TUN uses a virtual network interface to capture more traffic and also involves routing, DNS, and additional permissions. Android clients typically use the system VPN interface to route app traffic; Android displays an authorization prompt the first time. These methods determine how traffic reaches the core, not how the core chooses an outbound route. For your first setup, enable just one connection method. Verify it works before adding anything else, and avoid running multiple proxy tools that may overwrite the same network settings.

Menu names in this guide are intended to help you find features; they may not match every client's interface exactly. Updates can move settings, so look for features such as “subscription groups,” “system proxy,” and “routing” rather than relying on button colors or fixed screen coordinates. For runtime, permission, or driver prompts, read the current release notes and system dialog. Do not switch all routine use to elevated privileges just because an older guide recommends running as administrator. Once setup is ready, follow the section for your platform instead of mixing instructions from different operating systems.

Windows: Install v2rayN and configure the system proxy

Choose the desktop or classic WPF edition

Open the Windows downloads and choose between the desktop edition and classic WPF edition. The desktop edition uses a cross-platform interface, while WPF retains the classic Windows interface; menus, settings, and dependencies may differ. Choose based on system compatibility and your preferred workflow, and do not install both editions over the same directory. The download section provides installers for specific architectures. If your device's architecture does not match, check the current release notes first—do not assume any package will run natively just because it says Windows.

Once downloaded, install the file or extract the entire archive, as appropriate. For archives, extract all folders and keep the client and bundled core files in their original relative locations, then launch the client from the extracted folder. If the first launch reports a missing runtime, install the component that the current program specifies for your architecture; do not randomly add multiple runtime packages. If Windows blocks the launch, check the file source, the specific reason shown, and local security records instead of disabling security protections altogether. If the interface opens but the core will not run, check that its files remain in the expected directory.

Import a subscription and select a working configuration

In subscription group settings, create a group, give it a recognizable name, paste the full subscription URL, and save. Saving the group and fetching its contents are separate steps: after saving, update the subscription and wait for configurations to appear. For a single share link, use the client's clipboard import rather than creating a remote subscription. After import, check that the protocol, transport, and security options match the provider's instructions, then set one configuration as active. Clicking a row to highlight it may not make it active; follow the client's status indicator.

If the subscription list is empty, check the update message for a connection, authentication, or parsing error. For connection failures, check whether the subscription request uses a direct connection or an existing proxy. For authentication failures, confirm the URL has not expired. For parsing failures, check whether the response is actually in a supported subscription format. Creating more groups with the same name will not fix the issue; it only adds duplicates and makes troubleshooting harder. If you already have a working configuration, keep it as a fallback while checking the new group rather than clearing everything and losing your connection.

Enable the system proxy, then add TUN only if needed

Start the active configuration first, then enable automatic system proxy setup. Check the system proxy settings to make sure the address matches the local endpoint the client is listening on and the port matches the client settings. HTTP, SOCKS, and mixed endpoints are not interchangeable: when configuring an app manually, use the matching port type. A browser with its own proxy extension may ignore system settings, so disable the extension's proxy handling while testing. Consider TUN only if apps that ignore the system proxy need to connect. Before enabling it, clear the system proxy to avoid interference from overlapping connection methods.

Handle permissions, clean shutdowns, and migration

TUN may require elevated permissions or a network component. Follow the current client prompts rather than running the entire program as administrator all the time. If TUN affects local printing, shared folders, or a corporate network, turn it off first and check whether routing capture is the cause, then add the direct-connection rules you need. Test other VPN or corporate access software one at a time; do not assume virtual adapters will coordinate automatically. If the connection misbehaves after sleep, stop and restart the service, then check that the virtual interface and DNS have recovered.

Before quitting normally, use the client's option to clear system proxy settings, then close the program. If the client exits unexpectedly, the system may still point to a local proxy port that is no longer listening, causing browsers to report a connection error. Reopen the client and clear the setting, or check the system proxy page and restore the previous state. Before moving the client to another directory, quit and back up its configuration, then move the entire folder. Do not run multiple instances that share a configuration directory. For more desktop interface details, see the complete v2rayN Windows setup guide. For troubleshooting, rely on the current logs.

macOS: Choose the right chip, manage permissions, and check network services

Choose the v2rayN build for your chip

Check the chip listed in “About This Mac,” then open the macOS downloads and choose the v2rayN installer for Apple Silicon or Intel. Do not infer the chip from the device's purchase year or treat architecture labels in filenames as optional. After downloading, open the disk image and follow its instructions to move the app to the usual Applications location. Launch it from there. The running app should not depend on a mounted download image, which can complicate updates, file paths, and removal.

The first time you open the app, macOS may ask you to confirm its source or may block it. Read the specific message first, then use the system's approved one-time open process after confirming the source and installation steps. Do not run commands that broadly remove system protections, or treat “developer cannot be verified” and “app is damaged” as the same issue. If the client interface works but the core exits, check architecture, execution permissions, and file paths in the logs. Repeatedly dragging the app icon will not fix a core that is incompatible with the runtime environment.

Create a subscription group and choose an active configuration

Open subscription management, create a separate group, enter the subscription URL, and update it. The group name is only for local reference; the URL and its parameters determine what is fetched remotely. To import a share link, make sure the clipboard contains the full link only—no chat text, quotation marks, or line breaks. After updating, choose an active configuration, check that the core starts, and then set up the system proxy. A configuration migrated from desktop may contain platform-specific file paths, such as rule or certificate files. Update those fields for the current system instead of reusing them unchanged.

The network path used for subscription updates depends on the client's update options and the current connection. If an initial update requires a proxy but no configuration is available yet, you can get stuck in a loop. Follow the provider's instructions to obtain an initial configuration, or check whether the subscription endpoint is reachable directly from your current network. Once you have a working connection, do not delete all existing configurations just to update a group. After updating, check that the active configuration still exists; a renamed remote entry may not be selected automatically.

Check the proxy status for the active network service

On macOS, proxy settings are associated with network services. After enabling the system proxy in the client, check the service you are actually using, such as your active Wi-Fi or Ethernet connection. Switching networks, connecting a dock, or changing service order can leave the proxy setting out of sync with the current connection. Whether a browser uses the system proxy also depends on its own settings; check browsers with independent proxy extensions separately. Verify with one app that uses system settings before testing others. Do not assume all system traffic is routed just because the menu bar icon is visible.

If the system proxy is working but a particular app still connects directly, the app may ignore system settings or use its own network stack. Consider TUN only if you need broader coverage, and follow the client's permission prompts. Before enabling it, note your existing proxy and DNS settings and stop other tools that capture network traffic. Corporate devices may have policies that prevent network changes; follow your device management requirements rather than repeatedly trying to grant permission. Even after authorization, confirm that the core is actually handling traffic by checking logs and real app requests.

Handle sleep, network changes, and proxy settings left behind

If the connection fails after waking from sleep, first confirm that macOS has reconnected to the network, then stop and restart the client service. If failures occur only after switching networks, check the active service's proxy settings, DNS, and any lingering connections instead of immediately changing protocols. Clear the system proxy before quitting normally. If the app closes unexpectedly and the browser keeps reporting that it cannot reach the proxy server, check whether the active network service still points to a local address. When restoring settings, undo only the changes made by this client; do not remove other settings required by your corporate network.

Before updating the client, back up subscription groups and custom routing rules, and note the selected core. After replacing the app, test your original simple configuration before restoring complex rules. If the new program cannot read the old directory, check the configuration storage location and current user permissions. Avoid copying the entire cache directory, which can carry over permission problems. Troubleshoot in stages: client launch, core startup, and system traffic capture. Check system messages if the app will not open, logs if the core exits, and the proxy path if only a business app fails. Working by stage preserves useful evidence and is more effective than repeated reinstalls.

Linux: Package formats, desktop proxy, and TUN permissions

Choose a package for your distribution and architecture

Open the Linux downloads, choose deb or rpm for your distribution, then confirm whether you need x64 or arm64. deb packages are commonly used on Debian, Ubuntu, and related distributions; rpm packages are common on Fedora and others. The same package format does not guarantee identical dependencies across distributions. Before installing, review dependency warnings from your distribution's package manager. Do not ignore errors and try to launch the app anyway. A graphical client needs a desktop session; headless servers are outside the scope of this guide, so do not apply desktop autostart or system proxy instructions to them.

Use your system's graphical software installer to open the package so the package manager can handle dependencies and register files. If it reports missing dependencies, note the component names and system version, then confirm that the package is intended for your distribution. Do not copy shared libraries from unknown sources into system directories, and do not confuse missing dependencies with missing execute permissions. After installation, launch v2rayN from the desktop application menu and check that the interface, configuration directory, and logs are accessible. Keep the client and core executables in the package's expected layout; copying only the main program to your desktop is not sufficient.

Import and run as a regular user

Launch the client as your everyday desktop user. Create and update a subscription group, or import a single share link. The current user must be able to write to the configuration directory; a previous launch with elevated privileges may have left files that a regular user cannot edit. If saving fails, check directory permissions and available disk space rather than raising the privileges of the entire program. After selecting an active configuration, check the core logs for issues such as a port conflict, missing files, or unsupported fields. The desktop edition's settings may resemble those on Windows, but local paths, permissions, and traffic capture work differently on Linux.

Keep custom rules, certificates, and external resource files in stable, readable locations, then select them in the client settings. Avoid temporary paths on removable storage, and do not assume absolute paths from another computer still exist. Remote server parameters in subscriptions are usually platform-independent, but supporting files and local listener settings are environment-specific and must be reviewed after migration. If a configuration imports but will not start, find the first specific error in the logs rather than relying on the interface's final “startup failed” summary.

Know what the desktop system proxy covers

On Linux, system proxy behavior depends on the desktop environment and each app's implementation; it is not a master switch that every program must follow. After the client updates desktop proxy settings, a browser may use them while some apps rely only on their own settings or environment variables. Test the browser, the target app, and client logs separately. One working app does not prove all traffic is captured. If the target app has manual proxy settings, choose the correct HTTP or SOCKS type and the port the client is actually listening on. Environment variables and desktop settings may also be configured independently.

Do not copy one address into every proxy field before confirming which listener type the client provides. HTTP, SOCKS, and mixed ports behave differently, and UDP support depends on the connection method and core configuration. For a local proxy, use a loopback address. Do not bind to all interfaces just to make one app recognize the proxy. LAN access is a separate configuration that requires attention to authentication, firewall rules, and access scope; it should not be part of a standard desktop setup.

Enable TUN only when needed, and distinguish permissions from policy

TUN uses a virtual network device, routing table, and DNS; the required permissions vary by package and system. Use the client's supported permission setup instead of granting broad permissions to its entire directory. If TUN fails, check whether the logs identify device creation, routing, or a permission denial, then review system policy records. Firewalls and system access controls can affect network capture, but the solution is to identify the specific rule—not to disable all protections. If you use container networking, a corporate VPN, or another virtual interface, disable one at a time to establish a minimal working setup.

Desktop autostart and a system service are not the same thing. Graphical clients usually depend on a user session. If you enable autostart, verify it after signing out and back in; do not mistake it for a long-running privileged service. If only TUN stops working after a system upgrade, check permissions, the virtual interface, and route restoration before assuming the client is incompatible. Revoke traffic capture settings before quitting normally, and check for leftover manual proxy settings if problems persist after a reboot. Include the desktop environment, distribution, architecture, and connection method in troubleshooting notes to help distinguish client issues from system differences.

Android: Import configurations and use VPN mode

Start with v2rayNG; choose v2flyNG when you need it

The Android downloads offer v2rayNG first, for configurations that use the Xray core. v2flyNG is an alternative for the V2Fly core. Choose based on the configuration's protocol and core requirements; similar names do not mean the apps are interchangeable. Most recent mainstream devices can start with arm64. If you are unsure of the architecture or the installer reports incompatibility, check your device details and consider the universal package. A processor's capabilities do not guarantee an identical runtime environment, so follow the requirements for your device and Android version.

Open the downloaded package in your system file manager and follow the prompt to allow this installation from the current source. The app requesting permission may be your browser or file manager; confirm which app you are authorizing and do not enable installation permissions for unrelated apps. After installation, open the client and locate its settings and logs before importing a configuration. If an update reports a signature conflict or cannot replace the app, back up your groups and configurations first, then check whether the old app and new package come from the same source. Do not uninstall first only to discover that your data was stored inside the old app.

Import subscriptions, share links, and QR codes

In subscription management, create a group, enter the full URL, save it, and then run an update. When copying the address, avoid including explanatory text from a chat bubble. If the provider gave you a share link, use the appropriate import option instead of pasting it into the subscription URL field. QR codes are useful for importing a single configuration, but check the protocol and parameters after scanning. If no entry appears, check the client message and clipboard contents. Avoid tapping import repeatedly and creating duplicates. Once the subscription update succeeds, select an active configuration and connect.

When moving between v2rayNG and v2flyNG, use a standard share format supported by both or ask the provider for a compatible subscription. Do not overwrite one app's data directory with the other app's internal data. Even with the same protocol name, security settings, transport options, and core extensions may differ—especially for configurations that rely on core-specific features. If only some entries appear after import, check the missing entries' protocols and formats. The number of entries alone does not prove whether the remote subscription is complete.

Authorize the VPN interface and test the connection

The first launch usually prompts Android to allow a VPN connection. Confirm that the request comes from the client you opened before granting access. Authorization allows the app to create a system VPN interface; it does not mean the remote connection succeeded. After connecting, check that the client reports the core is running, then test with an actual app. A VPN icon in the status bar only indicates that the interface is active; the server connection, DNS, or routing may still be failing. If another VPN is already connected, disconnect it before testing to avoid Android switching between connections or refusing to create a new interface.

App routing determines which apps use the VPN interface. The options “allow selected apps only” and “exclude selected apps” work in opposite ways, so read the current screen's explanation before choosing apps to test. Once traffic enters the interface, the core's routing rules still decide whether it connects directly or through a proxy. Selecting an app does not guarantee that all its requests use the same outbound route. For initial testing, disable complex app filters, verify a simple configuration, then add apps back one by one. Otherwise, an excluded browser may make it look as though the server is down.

Handle background restrictions, Private DNS, and network changes

If the connection drops when the screen turns off, check whether the system restricts the client's background activity, battery use, or autostart. Settings vary by device, so look for the app's background permission rather than following a path for a specific brand. Allow background activity, reconnect, and check whether the persistent notification remains visible. If the client is still running but only domain requests fail, check for conflicts between Android Private DNS, the client's DNS settings, and the network. Change one setting at a time, note the original value, and verify the result before keeping the change.

Switching between Wi-Fi and mobile data can invalidate an existing connection, and the client may need to reconnect. A brief reconnect does not necessarily indicate a configuration problem. If the failure persists, stop the connection, confirm that Android's own network access works, then restart the service. If the same configuration works on one network but not another, check whether the subscription endpoint and server are reachable on the failing network, and report the specific error to the provider. Stop the VPN before closing the client. If you need a persistent connection, check Android's always-on VPN and lockdown settings so a stopped client does not leave the device without network access.

Subscription management: formats, updates, and migration

Tell subscription URLs, share links, and full configurations apart

A subscription URL is a remote endpoint that the client uses to retrieve a set of configurations; its contents may change when the provider updates them. A share link usually describes one configuration and may not stay linked to remote updates after import. A full configuration file may include multiple sections, such as inbounds, outbounds, DNS, and routing. These formats are not interchangeable just because they look similar as text. If you paste a web page URL into a subscription field, the client may receive page content instead of configuration data. Importing a full JSON file as a share link may also fail. Identify the type of data you received, then use the matching import method to avoid common errors.

Subscription encoding and container format are only the outer layer; compatibility depends on the protocols and fields inside. Being able to decode a subscription does not mean every entry can run, and conversion cannot supply missing public keys, service names, or paths. If conversion is necessary, use a method with a clear, controlled source and understand that it will handle your subscription credentials. Do not submit personal subscription URLs to tools with unclear data handling. If a configuration depends on a core-specific feature, confirm the target client supports it before considering a format conversion. Conversion cannot force an incompatible configuration to work.

Break subscription updates into four stages

Subscription updates have four stages: reading the URL, making the network request, parsing the response, and applying entries to the list. A URL read error often points to whitespace, truncation, or encoding issues. Request failures may involve DNS, the connection path, authentication, or server status. A parsing error means the response is not in the expected format. If applying entries fails, check filters, duplicate handling, and the selected group. When logs show only a general failure, look for the first specific message. Troubleshooting by stage is more effective than switching cores, since a subscription request may not use the active proxy connection.

Before updating, check which network path the client uses for downloads: direct, through the current proxy, or another available method. The exact options depend on the interface. If your active configuration is broken and subscription updates depend on it, the two problems can compound. Keep a confirmed working configuration as a fallback and restore the update path if needed. For authentication failures, do not refresh repeatedly; check whether the subscription was reset, the account status changed, or the URL parameters are incomplete. A successful response with an empty list may mean there are no available entries. Check the message rather than creating more groups.

Manage groups, active configurations, and local changes

Create separate groups for different sources and give each a name that identifies its purpose or origin instead of piling everything into the default list. Subscription updates may replace remotely managed entries, and local edits to names or parameters may not persist. For custom configurations you need to keep, use the client's copy or standalone configuration feature and remember that they will no longer track the original subscription automatically. If a remote entry is renamed or deleted, the active configuration may stop working. After updating, check that the selected entry still exists and verify the core status again.

Restore data first, then restore system traffic capture

When moving to a new device, back up the old device first, then create a minimal setup on the new one. Restore subscriptions or share links, verify that the core starts, and only then restore routing, app filters, and autostart. System proxy ports, network interface names, local file paths, and permissions belong to the device environment and should not be copied unchanged. A full client backup can help restore a similar environment, but check the core choice and connection settings. Do not let sync tools write to the same active database on both devices at once; this can cause conflicts or lock the data.

Treat subscription URLs, exported files, and screenshots containing connection parameters as credentials. When asking for help publicly, include the error type, protocol name, and necessary field structure, but remove user IDs, server details, and access tokens. If a URL has been exposed, deleting the post does not revoke it. Reset it through the provider's available management tools, then update the saved URL on all your devices. For common format issues, see the FAQ. To understand the difference between subscriptions and configuration fields, consult the glossary so you can distinguish update failures from connection failures.

Proxy and routing: connection methods, routes, and DNS

Understand settings by following the traffic path

Think of the full path as: an app makes a request, traffic enters a local endpoint, the core matches a rule, selects an outbound, and connects to the destination. System proxy and TUN determine how traffic enters the path; routing rules determine whether it connects directly, through a proxy, or is blocked. If the client says “Global,” first check whether that means the system proxy's coverage or that the core sends all captured traffic through the proxy. Different interfaces may use the same label differently. Requests that never reach the local endpoint will not be captured just by changing the core's routing mode, which is why some apps continue to connect directly.

For ordinary browser use, start with the system proxy and enable TUN only if you need to capture more apps or protocols. An app bypassing a local address under system proxy may have its own exception list. Under TUN, direct connections may be controlled by core rules or excluded network ranges. First confirm that the request reaches the core, then check which rule it matches. Do not enable TUN, change DNS, switch to Global, and change servers all at once. Even if the connection comes back, you will not know which change fixed it.

Set clear priorities for routing rules

Most routing rules are checked in order, and the first match can determine the outbound. Give LAN traffic, specific service domains, and the default route clear positions. A broad rule near the top can prevent more specific rules below it from taking effect. Without a fallback action, unmatched requests may use an unexpected outbound. The example below is an Xray-style routing snippet that demonstrates direct connections to private addresses and matching a specific domain suffix. It is not a complete connection configuration. The corresponding outbound tags must already be defined; do not import this snippet as a complete server configuration.

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

In this example, domain:example.com matches the domain and its subdomains; it is not an address for testing a real service connection. direct and proxy are outbound tags and must match the tags in your configuration. The core must also be able to read the rule data used to identify private addresses. Graphical clients may generate tags and rules automatically. When using their routing editors, follow the current field conventions and do not mix syntax from different cores. Save the old rules before editing. Afterward, check that the configuration starts, then test which rules are matched.

DNS resolution and domain matching affect each other

DNS resolves domain names to IP addresses, but the domain may not remain available as a request passes through the app, local system, and core. If an app resolves the name itself and sends only an IP address, the core may not be able to match the original domain directly. Whether it can recover the domain depends on the connection method and related features. When choosing a DNS server, consider how it can be reached; do not set an address as your only resolver if the current network path cannot access it. If a domain fails to open but an existing connection still works, check the DNS path before assuming the protocol is incompatible.

FakeDNS uses virtual address mappings to retain domain information and must work together with traffic capture and domain recovery. It is not a standalone feature you can enable just by changing DNS servers, and it may affect LAN services, app caches, and network switching. There is no need to enable it just to make a new installation feel complete. If you need domain-based routing, note your current DNS settings, configure FakeDNS using a method supported by your client, and test it so you can fully revert if needed. For its principles and limitations, see How FakeDNS works.

Test routing with as few variables as possible

Test one target app and one connection method at a time. Confirm the request reaches the core before checking its outbound and DNS. If LAN access fails, check private network ranges and name resolution first; for remote services, check the protocol and server connection. When rule data needs updating, distinguish a rule resource update from a subscription update—they are separate actions. Xray and V2Fly do not support exactly the same configuration features, so review custom rules after switching cores. For ecosystem and feature differences, see Xray vs. V2Fly core differences. Renaming fields will not make incompatible configurations work.

Common setup issues: troubleshoot by failure stage

Troubleshoot installation and core failures separately

If the installer will not run, check system architecture, package format, and the installer's message. If the graphical interface opens but the service fails to start, check the core logs instead. Port conflicts, missing files, insufficient permissions, and unsupported fields can all stop the core, but each requires a different fix. The first specific error in the logs is usually more useful than the final failure summary. For a port conflict, check for an old instance or another program using the same port, then stop the conflicting process or change the listening port. Update the app and system proxy settings to match, or the change may cause a new connection failure.

For an unknown protocol or field error, check which core the configuration requires instead of deleting the reported field. Removing a security field may let parsing succeed while changing the connection behavior the provider intended. For missing files, check the install directory, resource paths, and security logs. For a permission error, identify the specific file or network operation instead of elevating the entire program. Full configuration files must also have valid JSON syntax, including correct commas, matching quotation marks, and the right field types. For more error categories, see Diagnosing v2rayN core startup errors in logs.

Connected, but websites won't load

“Connected” may mean only that the core or system connection interface started; it does not guarantee that every request will succeed. First check whether the app is sending traffic to the local endpoint: on desktop, check system proxy settings and any browser-specific proxy; on Android, confirm the VPN is still running and the app is not excluded. Next check the listening port, then DNS and routing, and finally the remote connection. If the logs show no target requests, fix traffic capture first. If requests appear but time out, check the outbound route, network, and server. Do not skip these steps and assume every problem is caused by a remote outage.

If only some websites fail, the cause may be a domain rule, DNS result, the destination service, or the transport—not a broken client. Compare different destinations in the same app, then try the same destination in another app to distinguish app settings from route issues. Avoid switching configurations repeatedly; allow each attempt to finish or report an error. For a step-by-step check of system proxy, DNS, and routing, see the connected but no internet troubleshooting checklist. Record the results before making further changes so temporary settings do not overwrite one another.

Subscription failures, handshake errors, and time issues

For subscription update failures, check the request path and response type. For a remote handshake failure, verify the server address, port, user ID, transport path, and security settings. For TLS errors, also check the system date, time zone, and server name field; do not hide the problem by disabling verification. The service name, hostname, and server address required by a configuration may be different. Enter each value as specified by the provider rather than substituting similar-looking values. Editing encoded parameters in a share link can also break its syntax. Reimport the complete original link, then compare it with the local entry.

If the same configuration works on another device, that only shows the remote endpoint worked under those test conditions; it does not prove the client on this device is defective. Compare the core, system time, connection method, DNS, network, and app filters on both devices, keeping conditions as similar as possible. If it fails only on a particular network, note whether the subscription endpoint is reachable and record the exact error and failure stage. Reinstall only after confirming that the configuration directory is damaged or the installation files are faulty. Reinstallation is no substitute for analyzing the network path and core errors; otherwise, the same problem often returns as soon as you import the same configuration.

Roll back updates, restore connectivity, and ask for help effectively

Before updating, export your configuration and note the current core, connection method, and custom routing rules. After updating, test a simple configuration before restoring extra features. If you need to roll back, keep a backup and check whether the older program can read the newer configuration format. Do not let different versions write to the same directory in turn. If the entire system loses network access after the client stops, check for leftover desktop proxy settings, then confirm that TUN, VPN, and manual DNS settings have been cleared. On Android, check whether the system blocks traffic when the VPN is unavailable. Change only settings related to this client.

When asking for help, include your platform, architecture, client name, selected core, failure stage, last change, and an error excerpt with sensitive details removed. Mention whether only one app fails, whether the issue started after switching networks, and whether connectivity returns when the client stops. This is more useful than simply saying “it won't connect.” Do not post a full subscription URL, connection QR code, or unredacted configuration file. After fixing the issue, retest under the same conditions and remove temporary settings you no longer need. To repeat the minimal connection steps, return to the quick-start guide. For specific concepts or common symptoms, see the FAQ and complete the loop from setup to verification and troubleshooting.