Install and Configure Clients on Every Platform

Before you begin: check these three things

Before you start, check your device, client, and connection details separately. Your operating system determines which installer to use; your processor architecture determines whether the app can run; and your subscription determines whether the client can generate a usable config. These are separate requirements. Installing a client does not give you a working server, and importing an entry does not mean the remote service is still available. Note down what you have before troubleshooting so you don’t end up reinstalling repeatedly.

Check your OS, architecture, and core requirements

For desktop platforms, v2rayN is the recommended choice. The Windows download page offers a desktop edition and a classic WPF edition; the main differences are the interface and runtime, not the subscription account. On macOS, choose a build for Apple Silicon or Intel. On Linux, check both processor architecture and package format. Don’t guess the architecture from the file extension, and don’t try to open a desktop installer on your phone.

For Android, v2rayNG with the Xray core is the default choice. If your existing config specifically targets V2Fly, consider v2flyNG. A core isn’t a visual theme: it parses configs, handles protocols, and establishes connections. Configs that require features such as REALITY need a compatible core. Similar import menus don’t mean two clients support interchangeable fields.

Also check that your device time is set to sync automatically, there’s enough disk space, and your system allows apps from the chosen source. A significantly incorrect clock can interfere with certificate checks and some authentication flows. For initial troubleshooting, use a stable, ordinary network and avoid running multiple proxies or VPN tools at once. Otherwise, it’s hard to tell which one is handling your traffic.

Subscription URLs vs. single share links

A subscription URL is usually an updateable web address that returns multiple connection profiles. A single share link describes one server config. Copy the complete text, without chat app explanations, quotation marks, or line breaks. An account management page in your browser may not be a subscription endpoint. A page opening successfully doesn’t mean its URL belongs in the “Subscription groups” address field.

A subscription URL may contain account credentials, so treat it like a password. Don’t post it publicly, include it in an error screenshot, or upload a config backup containing it. When asking for help, share the error type, steps to reproduce, and client name instead. If the URL has been exposed, reset it through the service’s account management tools; deleting the group from your client is not enough.

If you already have an older client, use its export or backup feature to save your settings first. Note your subscription group names, active server, routing preset, and local listening ports. Store the backup somewhere you control. During migration, import and verify one subscription before moving the rest. Copying everything at once can carry over port conflicts, outdated rules, and invalid links.

Set up a repeatable baseline test

For your first connection, select one server, leave TUN off, and use the default routing and system proxy settings. Check whether the client starts the core, then whether your browser uses the system proxy, and finally whether the target page loads. Change one setting at a time and repeat the same checks. This separates installation, connection details, and traffic interception issues without relying on whether the config merely “feels faster.”

Enable detailed logs temporarily when you need to reproduce an issue, then restore the normal log level. Redact addresses, user identifiers, and subscription credentials before sharing. A useful failure report says what you did, what appeared on screen, and what happened next—not just a screenshot of a red warning. For the shortest path to a working connection, see the quick-start guide. The following chapters explain platform-specific differences.

Windows: Install and Configure v2rayN

On Windows, install the client, complete the first launch, import a subscription, and then enable the system proxy—in that order. Don’t turn on every option at once. Seeing the client window only confirms that the interface is running. Check separately that the core started, the local port is listening, and your browser is using the proxy. If something fails, step back through these checks before switching servers; it makes the cause easier to find.

Choose the desktop or classic WPF edition

Visit the Windows downloads and choose the v2rayN desktop edition or classic WPF edition. The desktop edition uses a cross-platform interface; the classic WPF edition keeps a familiar Windows desktop layout. Menu locations may differ, so this guide refers to features such as “Subscription groups,” “System proxy,” and “Routing settings.” Labels may vary in your version; the instructions don’t depend on fixed button positions.

Follow the installer prompts, then launch the app from the Start menu or installation folder. If Windows reports a missing runtime, check the component name and architecture in the message, then follow the app’s guidance. Don’t download individual DLLs from unfamiliar websites and copy them into the program folder. If the installer won’t start, check Windows security alerts, confirm the download completed, and see whether app installation is restricted on your device.

Run the app as a standard user for your first setup. The system proxy usually doesn’t require administrator rights; TUN may require elevated permissions or additional network components. Don’t run every networking app as an administrator just to avoid a permission prompt. If the interface opens but the core exits immediately, check the logs for a port conflict, a read-only file path, or a core startup error, then address the cause shown.

Create a group and update the subscription

In “Subscription groups,” add a group, give it a recognizable name, and paste the complete subscription URL. Save it, then run an update and confirm it applies to the group you just added. For a single share link, use the import-from-clipboard feature instead; don’t paste the entire share text into the subscription URL field. The resulting entries may look similar, but only a subscription group retains the source for future bulk updates.

When the update finishes, clear any keyword filter in the server list and check that the right group is selected. An empty list doesn’t always mean the download failed; a filter may be hiding every result. Select a server and make it active, then confirm its protocol matches what you expect. If several entries have the same name, organize them by source group instead of assuming the suffix tells you whether their connection details match.

If a subscription update fails, first check whether the URL was truncated or you copied an account webpage instead. Then look at the specific error. Some subscriptions require an existing proxy to access; in that case, first confirm a connection is working, then try updating through the proxy. Don’t keep switching update methods when you have no working connection. For details, see the subscription update troubleshooting checklist.

System proxy, TUN, and Windows-specific issues

Under “System proxy,” select “Automatically configure system proxy,” then test with a browser that follows system settings. “Clear system proxy” removes settings written by the client; “Do not change system proxy” leaves the current settings as they are—it doesn’t turn the proxy off. If another tool set a proxy earlier, choosing “Do not change” may keep its old address active. Check the actual value in Windows settings when troubleshooting.

If your browser works but some apps don’t, first check whether those apps use the system proxy. Enable TUN only if you need to capture their traffic; follow the authorization prompts and check the virtual adapter and core logs. If enabling TUN cuts off all network access, turn it off immediately and return to the verified system proxy baseline. Then check the virtual adapter, routing conflicts, and other network tools one at a time. Don’t change DNS and multiple routing rules together.

If the connection stops working after waking from sleep, the network interface may have changed or another tool may have overwritten the settings. Reselect the active server, then reapply the system proxy. If the browser can’t load pages after an unexpected exit, check the local address in Windows proxy settings. A proxy pointing to a port owned by a closed client won’t respond. Before restoring settings manually, make sure they aren’t managed by your organization.

Set up startup behavior, automatic subscription updates, and default routing only after your first connection works. If a firewall prompt asks about the listening scope, keep it limited to this device; browser access doesn’t require allowing connections from your local network. If the logs report a port conflict, close the older instance or choose an unused port in the client settings. Update any apps using a manually configured proxy as well, so both ends point to the same address.

macOS: Choose the right chip and grant network access

When using v2rayN on macOS, check your chip first, then install the app and grant the required system permissions. The app launching, its menu bar status appearing, and system network requests using the proxy are three separate outcomes. A Mac may have Wi-Fi, Ethernet, and virtual interfaces active at the same time. After switching networks, check the proxy status on the interface currently in use rather than relying on the client’s toggle alone.

Choose a build for your chip and open the app

Open “About This Mac” and check “Chip” or “Processor.” Apple Silicon uses the arm64 installer; Intel uses the x64 installer. Choose the matching build from the macOS downloads. Don’t guess based on the device’s appearance or purchase date. A native build is usually the best fit. If the wrong architecture won’t run, download the correct installer instead of layering on a compatibility workaround.

Open the downloaded disk image and follow the window instructions to move the app into “Applications.” Launch it from there. Don’t keep running it from the mounted installer; updates, file locations, and behavior after quitting can become confusing. If you already have an older version, quit it before replacing the app. Otherwise, one window may be running from the old location while your launch shortcut points to the new one.

If macOS blocks the first launch, check the file’s source and app name, then follow the prompt for that app in “Privacy & Security.” Don’t disable system-wide security to open a single app. On a managed device, your administrator may need to approve it. When a permission dialog appears, make sure it was triggered by the app you just launched, not another background process.

Import a subscription and check the active profile

Open the subscription groups feature in v2rayN, add a group, save the URL, and run an update. If copying text from a browser doesn’t import correctly, paste it into a local text editor you control and check that it’s complete. Don’t submit credentials to an online conversion tool. A subscription may return an error page; receiving content doesn’t mean it was parsed successfully. Check the update result in the client.

After updating, select the target group, clear any list filters, and set an active server. For the first test, keep the generated config at its defaults; don’t immediately change transport or security settings. The server name, connection address, and certificate verification name in the original details may differ. Manually swapping fields because their names look similar can make the interface appear fine while the encrypted connection fails.

You can name multiple subscriptions separately. Verify one before adding the others. Set an automatic update interval only after manual updates work reliably. Missing an update while the Mac sleeps isn’t necessarily an error; you can run one after waking. If old entries remain, don’t delete everything in bulk. Check for individually imported profiles and make sure you’re viewing the group that was just updated.

Check the system proxy and TUN permissions

After enabling automatic system proxy configuration, open “Network” in System Settings, select the network service you’re using, and inspect its proxy details. The path may vary by macOS version, but the key is to check the active network service. If an automatic proxy configuration script was already set up, record its value so you can restore your original working environment after the client takes over.

Start by testing in a browser that follows the system proxy. Some apps have their own proxy settings; others don’t use the system proxy at all. That doesn’t mean the subscription disappeared. Try TUN only if you need broader traffic capture, and follow the permission prompts for the app and macOS. If it still doesn’t work after authorization, check the logs to confirm a virtual interface was created instead of relying on the toggle’s state.

When switching between Wi-Fi and Ethernet, or reconnecting after sleep, first confirm the network has assigned an address, then reapply the proxy. If only one network environment fails, compare results using the same server and routing setup. Public Wi-Fi may require its normal sign-in process first. A successfully started client core can’t replace network authentication.

Before quitting the app, remove the system proxy it set, or confirm the app is configured to restore it when it exits normally. If pages stop loading after an unexpected exit, check whether the active network service still points to a local endpoint that is no longer running. Preserve any existing work configuration; don’t clear every network service at once. For more general issues, see the FAQ. Not every network change means the app is damaged.

Linux: Package formats, desktop proxy, and permissions

Linux distributions, desktop environments, and permission models vary widely. This chapter focuses on v2rayN in a graphical desktop: install the package with your system’s software installer, then configure subscriptions and proxy settings in the client. Keep the roles separate: the package manager installs files, the desktop environment handles some system proxy settings, and the core and network interfaces handle the connection. Troubleshoot each layer on its own.

Check the package format and processor architecture

Choose an installer from the Linux downloads. Use a deb package for a deb-based distribution or an rpm package for an rpm-based one, and check whether you need x64 or arm64. Package format and processor architecture are separate requirements; getting one right doesn’t guarantee the package will install. Check your architecture in the system’s About or hardware information screen instead of guessing from the device brand.

Open the package with your distribution’s software installer. Review dependency and permission prompts before installing. If dependencies are missing, check that your distribution is supported and its software sources are available, then use the system’s repair option. Don’t force installation past dependency checks or copy low-level libraries from another distribution; doing so can make future updates and removal unreliable.

After installation, launch the app from the application menu. Don’t run the entire graphical client as an administrator by default. User and administrator settings are usually stored separately; mixing them up can make an imported subscription seem to disappear or leave the config directory with the wrong permissions. If you previously ran the app with elevated privileges, first check that your regular account can write to its own app settings.

Import a subscription and check desktop proxy coverage

Add a subscription URL in Subscription groups, save it, update the group, and select an active server from the list. If a copy-and-paste import looks incomplete, check for terminal line breaks, webpage instructions, or full-width characters in the clipboard. Keep advanced transport settings at their defaults for the first connection. If parsing succeeds but you still can’t connect, check the core logs instead of repeatedly importing the same URL.

After enabling the system proxy, open your desktop environment’s network proxy settings and check the mode and local endpoint. Desktop environments handle system proxy settings differently. Some apps read only their own settings; others rely on environment variables set at startup. A working browser doesn’t prove that background services, sandboxed apps, or command-line tools use the same proxy.

If a graphical app has its own proxy settings, enter the listening address, port, and protocol shown in the client. Don’t enter a SOCKS endpoint in a field that accepts only HTTP proxies, or use a subscription URL as the proxy server address. Restart the app after changing its settings so it doesn’t keep using network settings cached by an older process.

TUN permissions, interface conflicts, and recovery

Enable TUN only if you need to capture traffic from more apps. It involves a virtual network interface, routing, and network permissions; follow the prompts from your client and distribution. If the interface shows TUN as enabled but the logs report that the interface couldn’t be created, resolve the permissions and runtime issues first. Don’t blame the remote server or loosen access permissions for the entire app directory.

Before enabling TUN, close other network tools that perform similar interception and check for routes your system needs to keep. Containers, virtual machines, and remote work networks may use subnets that overlap with new routing rules. If local network services become unreachable, turn off TUN to verify that access returns, then add the necessary direct-connection rules. Don’t replace the default route on every interface at once.

If the system proxy remains set after quitting, restore its previous mode in your desktop network settings. If problems persist after disabling TUN, check whether the client stopped its related processes, then see if another tool has taken over networking. Be especially careful on remote desktop devices. Make sure you have a local recovery option before changing routes so you don’t lose your management connection.

Set up launch-at-login and automatic subscription updates last. Starting a graphical client before the desktop session is ready may leave it without access to the desktop proxy service. Updating a subscription before Wi-Fi connects can fail temporarily. First confirm that manual launch, manual updates, and proxy restoration on exit all work reliably. Then enable automation to distinguish session startup order issues from connection detail problems.

Android: Import profiles, grant VPN access, and keep the app running

For Android, start with v2rayNG; choose v2flyNG only when you need the V2Fly core. Their basic installation and import steps are similar, but their core capabilities aren’t interchangeable. On a phone, the Connect button typically uses Android’s VPN interface to capture traffic. That’s different from setting a system proxy for a desktop browser. Knowing the difference saves time looking for a system proxy setting that you don’t need.

Choose an architecture and install the app

Go to the Android downloads. For most recent mainstream devices, arm64 is the usual choice. If you’re unsure of the architecture or see an incompatibility warning, consider the universal build and check the device’s system requirements. A universal build covers more architectures; it won’t make an older OS meet the app’s runtime requirements. Don’t assume an installation error is a subscription or server issue.

When you open the installer, Android may ask you to allow app installs from the browser or file manager you’re using. Grant permission only to the source you’re actually using, and turn it off again afterward if you prefer. Save any settings you need before updating an existing app. If Android reports a signature mismatch, don’t uninstall immediately: first confirm the installer source matches the original app, since uninstalling may delete local data.

After the first launch, make sure the app opens normally before importing connection details. Device security or work profile policies may restrict VPN use; successful installation doesn’t mean Android will allow a VPN connection. On an organization-managed device, follow its policies instead of repeatedly reinstalling the app to get around restrictions. Keep the system clock set to sync automatically as well.

Subscription groups, share-link imports, and active profiles

Add a name and subscription URL in Subscription groups, save the group, and run an update. Menu labels vary by client and version, so look for the feature rather than an exact label. For a single share link, use import from clipboard or the relevant scan option. Don’t paste an account dashboard webpage as a subscription. When the imported profile appears, select it to make it active.

Entries in the list don’t guarantee that the right one is selected. After updating, check the group, protocol, and source; names may be identical. If a subscription uses an Xray-specific feature, test it in a compatible client. Don’t remove security fields at random just to clear a parsing error. To understand the differences, read the Xray vs. V2Fly core selection guide.

If an update reports success but the list is empty, check group visibility and filters, then review the update log. If the response is a login page or error page, changing clients usually won’t fix the URL itself. If the network is unreachable, try again on a working network but keep the subscription URL unchanged. Changing the network, URL, and client all at once leaves you with no way to identify the cause.

VPN traffic capture, per-app routing, and background limits

When you tap Connect, Android displays a VPN connection request the first time. Confirm the requesting app is correct before granting access. A VPN icon in the status bar only shows that Android created the interface; it doesn’t confirm that the remote server works. Next, open the target page in a browser and check the client logs. Work apps with their own VPN may conflict; typically, only one standard VPN service can be active in a user profile at a time.

Android doesn’t need the desktop system proxy steps. If only certain apps bypass the proxy, check whether per-app proxying is enabled and whether the list means “proxy only selected apps” or “exclude selected apps.” These modes do the opposite of each other. After changing the selection, disconnect and reconnect, then reopen the target app so an existing connection doesn’t keep using its old route.

If the connection drops when the screen locks, check battery optimization, background activity, and auto-start settings. Menu locations vary by device, so adjust them for this client rather than disabling power saving across the entire phone. Leaving the app in Recents may not be enough. On the other hand, allowing background activity won’t fix an invalid subscription. First verify that the connection works in the foreground, then troubleshoot background behavior.

After switching between Wi-Fi and mobile data, confirm the underlying network can open a regular webpage, then reconnect. If Android’s “Always-on VPN” or “Block connections without VPN” is enabled, the whole device may appear offline after the client exits. Check what these settings do before temporarily disabling them for troubleshooting. Once things work again, set them according to your needs instead of mistaking Android’s network blocking for a frozen client.

Proxy and routing: separate the entry point from the exit

Think of proxy settings in two layers. The first determines how app requests reach the client; the second determines which exit handles them. System proxy and TUN mainly handle the first layer, while routing rules handle the second. Enabling TUN doesn’t mean every request will use a proxy exit, and a direct-route rule doesn’t mean traffic bypassed the client. Trace the request path before interpreting labels such as “Global” or “Bypass.”

System proxy modes and the limits of TUN

“Automatically configure system proxy” directs apps that follow system settings to a local endpoint. “Clear system proxy” removes the relevant settings; “Do not change system proxy” leaves the current state untouched. These aren’t connection quality levels. If the core has stopped while the system still points to its port, the browser will fail. If the system proxy is cleared, the browser may connect directly even while the core is still running.

TUN receives traffic that matches its capture rules through a virtual network interface. It can help with apps that ignore the system proxy, but it also adds permissions, routing, and DNS coordination to troubleshoot. The two methods can coexist in some setups, but avoid enabling both during initial troubleshooting. First verify the system proxy path; then add TUN so you know whether the new capture layer introduced the problem.

Start with a preset, then add the smallest rule you need

For your first setup, choose a suitable routing preset provided by the client and confirm the basic connection works before configuring a specific website or local network service. Rules are generally matched in order, so an earlier broad rule can override a later, more specific one. After adding a rule, check its position, match type, and exit name. Adding a domain to a list but assigning the wrong exit can produce the opposite of what you intended.

geosite:cn refers to a matching domain collection, and geoip:private refers to a private IP address collection. Both depend on the runtime providing the relevant rule data; they aren’t automatically available in every config. direct is usually just a label chosen by the config author for a direct-connection outbound. A rule reference only works if an outbound with that name exists; the label isn’t a built-in automatic route.

If a local printer, home storage device, or router admin page stops working, check whether private IP addresses are routed directly and whether the target name resolves to the correct local address. Local network discovery may also rely on broadcast or multicast, which isn’t the same as opening a webpage. Don’t route all requests directly just because a device list is empty; test direct address access and automatic discovery separately.

Consider DNS alongside your test method

Domain rules need the client to know the requested hostname; IP address rules depend on the destination address. If an app resolves names itself, uses encrypted DNS, or sends only an address through the proxy, the match conditions may change. DNS behavior also depends on how the client captures traffic. For a domain access failure, check the resolution result and routing logs before disabling certificate verification or replacing every DNS server at random.

Browser secure DNS, system DNS, client DNS, and DNS interception by TUN may all be active at once. Note which layer handles resolution before changing anything. If only the browser behaves differently afterward, check its own settings. If every app fails, revisit the system network and traffic capture layer. Cached DNS results can affect tests, so restart the target app after making a change to establish a fresh connection.

To test a rule, keep the target and active server fixed, change one rule, and check which exit handles a new request. Cached pages, existing long-lived connections, and connection reuse can delay the result. Close and reopen the target app, and reconnect the client if needed; don’t just refresh the same page repeatedly. Make sure log entries match the time of your test rather than an earlier request.

“Global” can mean traffic capture in one client and a routing preset in another. When reporting an issue, name the specific menu and option. More rules don’t mean more accurate routing. Keep a note of what each custom rule does so you can revert changes in order. Configure only the sites and apps you actually need; there’s no reason to enable every advanced option at once.

Config files: from inbounds to routing

Graphical clients usually generate a runtime config from server, subscription, and routing settings. A single choice in the interface may affect several config fields. Reading the generated file can help with troubleshooting, but manual edits may not persist: changing servers, updating subscriptions, or restarting the core may regenerate it. For settings you need to keep, use the interface or a clearly designated custom config option whenever possible.

Key fields and tag references

inbounds defines the local entry point for incoming requests, including its listening address, port, and protocol. outbounds defines the exits used by outgoing requests, and routing maps requests to those exits. An inbound port is not the remote server port. Mixing them up can stop local apps from connecting or make the core connect to the wrong destination.

tag is a reference name; keep it clear and unique within the config. A routing rule’s outboundTag must point to a defined outbound, with matching capitalization. log controls logging behavior, and dns defines the core’s DNS settings. Neither can replace a missing outbound or correct invalid authentication details in a subscription.

Understand the structure with a working direct-connection config

The example below is an Xray direct-connection config. It exposes a SOCKS inbound only on the local loopback address and sends requests through a direct outbound. It contains no remote proxy server and doesn’t send traffic to a subscription server. Use it to understand the config structure, not to overwrite a production config generated by your client. To use it, save and select it separately through a custom config option.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}

The listening port in the example must be free. If the client’s current core already uses that port, stop the old config or choose another port in a separate config, then update the test app’s endpoint to match. This example combines local-only listening with no authentication because access is limited to this device. Don’t change the listening address to all network interfaces without first assessing the risk.

The SOCKS inbound in this config can’t be used as an HTTP proxy. If a browser or app explicitly supports SOCKS, enter the local address and matching port. A field that accepts only HTTP proxies can’t use the same protocol. A SOCKS inbound that supports UDP doesn’t guarantee the entire connection will work; the app, capture method, and outbound must all support the required transport.

Safe editing and recovery

JSON object keys must use double quotes. Standard JSON doesn’t allow comments, and a trailing comma after the last member is invalid. Don’t wrap boolean values or numbers in quotes just because that’s how they were copied. If parsing fails, check near the reported line and column for a bracket, quote, or comma problem. Don’t keep changing network settings until the config parses successfully.

Valid syntax is only the first step. The core then checks fields, protocols, and references before attempting a network connection. Categorize errors as “text parsing failed,” “config validation failed,” or “connection failed” to narrow down the cause. If the logs report an unknown field or unsupported security mode, check the core type and config source first. Don’t remove critical fields just to make the client start.

With TLS or REALITY, the server address, verification name, and other negotiation parameters each serve a different purpose. Enter them exactly as provided. Don’t treat a server certificate error as a simple toggle problem, and never disable verification permanently just to clear a warning. Check the device clock, whether the details have expired, and whether the selected core supports the required feature. Then ask the provider to confirm the parameters if needed.

Custom configs often don’t inherit all the options from the graphical interface. Changing routing in the UI may not update the rules in a separate config, and editing a file may not update the server list. For a closer look at how the sections fit together, read the V2Ray config JSON structure guide. First confirm which config is in use and where it takes effect, then choose how to edit it.

Config troubleshooting: check where the failure occurs

Start troubleshooting by identifying the step that failed. An installation failure points to the runtime environment; a subscription failure points to fetching or parsing connection details; a core startup failure points to local config; and a webpage that won’t load after startup calls for checks along the traffic path and remote connection. The sections below are organized by common symptoms. Restore the minimum working setup first, then add advanced settings back one at a time instead of switching options at random.

Subscription errors, empty lists, or unsupported protocols

If a subscription update times out, check the underlying network first, then confirm the URL is complete and whether an existing proxy is required. If content arrives but parsing fails, check whether the response is an error page and whether the format is supported by your client. An expired link, account status change, or outdated client could all be the cause; check the specific error instead of assuming the source is fine because it worked yesterday.

If an update succeeds but no entries appear, clear keyword filters, check the current group and hidden entries, then confirm which group you updated. Don’t immediately delete and recreate every group. If you have multiple subscriptions, disable unrelated groups temporarily to reduce confusion from duplicate names. For organization tips, see v2rayN subscription groups and filtering.

If a protocol or field is unsupported, first check which core the config requires. Changing the interface theme, port, or TUN settings won’t add protocol support. On desktop, check the core type for the active v2rayN profile; on Android, choose a client that matches the Xray or V2Fly requirements. After switching clients, test one profile before importing the rest.

Connected, but webpages won’t load

Check whether the client merely started the core or has logged an actual request. If no request reaches it, check the system proxy, the app’s own proxy settings, or the TUN capture scope. If a request appears but fails, inspect the remote address, authentication, transport, and DNS. A connection icon reflects local status; it doesn’t replace testing access to the target.

If all domains fail but some direct IP addresses work, DNS is worth checking, but that alone doesn’t prove it’s the cause. Secure sites usually depend on matching the domain to the certificate; opening one by IP and seeing a certificate warning isn’t a valid equivalent test. Use resolution errors, request targets, and outbound selection in the logs to investigate. Don’t ignore certificate warnings just to complete a test.

If only one site fails, keep the same config and test other working destinations, then check that site’s routing, app cache, and remote restrictions. If only one app fails, check whether it uses the system proxy or is excluded by per-app rules. If switching servers fixes it, note what changed and keep investigating; one successful test doesn’t prove the entire config is correct.

If enabling TUN cuts off network access across the device, turn it off, remove the extra traffic capture layer from your test, and return to the system proxy setup that worked before. Then check permissions, the virtual interface, other VPN tools, and DNS capture one at a time. If you manage the device remotely, keep a local recovery option and don’t repeatedly change routes over your only management connection.

Quitting, updating, and moving to another device

If webpages stop loading after you quit the client, check whether the system still points to a local proxy that has stopped. Restore the original system proxy settings first, then check the underlying network. On Android, also check Always-on VPN and the block-without-VPN option. Don’t reset the network as a first step; that can also erase Wi-Fi, work network, and other settings you need to keep.

If something breaks after an update, quit the old instance normally and check the new launch shortcut and config directory. Don’t keep two auto-start entries enabled. If you use a custom config, confirm the updated core still supports its fields. If the client generates the config from a subscription, retest with the default options first. Keep a backup before migrating so you don’t erase your only rollback option during an update.

When moving to another device, migrate the subscription source and only the rules you need rather than copying the entire traffic capture setup. Local ports, listening addresses, permissions, and interface names may differ on the new device. First verify one connection, then add groups, automatic updates, and routing rules. Once you’re done with the old device, remove its system proxy and auto-start settings to avoid lingering background behavior.

If you need more help, include your operating system, client name, core type, the step that failed, a redacted error message, and whether TUN was enabled. Don’t share your full subscription URL or account credentials. For other issues, check the FAQ. If you haven’t made a successful connection yet, return to the quick-start guide and follow the default setup from the beginning.