BEFORE START

Check These Three Items First

You only need the client, a valid subscription URL, and the correct system time. Confirming these basics first helps avoid backtracking later.

Platform-Specific Tips

The v2rayN desktop client is typically operated through the top menu, server list, and tray menu; v2rayNG on Android mainly uses the side menu, top-right action buttons, and bottom connection button. Their menu layouts differ, but the setup order is the same: save the subscription, update the configurations, choose a mode, then connect.

Before you begin, make sure the appropriate client is installed. Use v2rayN on Windows, macOS, and Linux desktops, and v2rayNG on Android devices. This guide does not require writing a complete kernel configuration or understanding every protocol field. A subscription service packages the server address, port, transport, and authentication details into a configuration the client can read. For a first setup, make sure the subscription URL is complete and still valid.

The second item is your device time. Connection authentication and TLS handshakes depend on the correct date, time, and time zone. If the system clock is significantly off, the client may update the server list successfully but then time out or fail the handshake repeatedly. Enable automatic date and time zone settings, then fully quit and reopen the client. Your network must also be able to reach the subscription URL. If opening it directly in a browser shows an expired notice, access denial, or server error, resolve that with the subscription provider instead of repeatedly changing client settings.

The third item is a clear fallback path. During your first setup, avoid changing custom DNS, complex routing rules, TUN parameters, and the system firewall at the same time. Fewer variables make problems easier to isolate. Complete one connection check with the default settings first, then adjust routing and DNS for your needs. Terms such as protocols, transport layers, TLS, and subscription groups are covered in Concepts at a Glance; systematic troubleshooting is covered in the Troubleshooting Handbook.

SUBSCRIPTION

Import the Subscription and Update the Server List

This stage is complete only when selectable server configurations appear in the client's main list—not merely when the URL has been saved.

v2rayN Desktop Steps

After opening v2rayN, find the “Subscription Group” menu and open “Subscription Group Settings.” Menu placement may vary slightly between versions, but the settings window always provides fields for adding a group, entering an alias, and entering a subscription URL. Create a group and name it by purpose, such as “Daily” or “Backup.” The name is only for local identification and does not affect connections. Paste the full subscription URL into the address field, taking care not to copy leading or trailing spaces from a chat app or document.

Saving the group does not mean the servers have already been imported. Return to the main window, open the “Subscription Group” menu again, and choose “Update All Subscriptions,” or update the group you just created. During the update, the client requests the subscription and parses its configurations. Normally, several server entries will appear in the main list, often showing aliases, addresses, ports, or protocol types. Do not rush to test latency one by one; as long as the list is not empty, continue to the next step.

If the new group is completely missing after saving, reopen Subscription Group Settings and confirm that the record exists. If the group exists but the list remains empty after updating, check the status information at the bottom of the client or open its log window. Common causes include an incomplete URL, an expired subscription, an unreachable subscription endpoint, or a server response in a format the client cannot recognize. Do not click Update repeatedly in quick succession. Read the result of one update first, then respond to the message it provides.

v2rayNG Android Steps

Open v2rayNG and go to “Subscription Group Settings” in the side menu. Tap the add button, enter the group name and subscription URL, then save. Return to the main screen and choose “Update Subscription” from the top-right menu. Some interfaces require you to select a subscription group before updating; if you have several groups, make sure the action targets the one you just added. When the update finishes, the main screen should show a server configuration list rather than a blank page.

Android may restrict an app's background network access. During the first update, keep v2rayNG in the foreground until the operation finishes. If the system interrupts the update, reopen the client and try once more. Once the server list appears normally, there is no need to import the same URL again. Creating multiple identical groups makes later configuration selection and troubleshooting harder.

What Completion Looks Like

After this step, the client's main list should contain at least one selectable configuration, and the update should not continue showing parsing errors. The server name does not need to be easy to understand; what matters is that the configuration has entered the client. The next question is which traffic the client should handle, so leave the list unchanged and do not modify low-level parameters for individual configurations yet.

subscription-group

Group Name: Daily Configuration
Subscription URL: https://example.invalid/sub
After Saving: Update All Subscriptions
Completion Status: Server Configurations Appear in the Main List

Next: Choose a Proxy Mode →

PROXY MODE

Choose a Proxy Mode and Traffic Scope

The server configuration determines where to connect; the proxy mode determines which traffic enters the client. These are separate settings. Selecting a server alone is not enough if the system proxy or connection mode is not configured.

First, Distinguish Routing from the System Proxy

On the v2rayN desktop client, two common settings are “Routing Mode” and “System Proxy.” Routing mode decides whether traffic entering the core is proxied, sent directly, or blocked. The system proxy makes browsers and other apps that follow system settings send requests to v2rayN. If you change the routing mode without enabling the system proxy, browser traffic may never enter the client. If you enable the system proxy but select the wrong active server, the local proxy may appear to be running while external connections continue to fail.

For a first setup, use the client's rule-based routing mode. It follows built-in rules and is suitable for checking whether ordinary browsing works. Global proxy sends more requests through the current configuration, which can help determine whether routing rules are misclassifying traffic, but it is not recommended as a long-term mode before the basic connection is confirmed. Direct mode temporarily disables the proxy path; if selected by mistake, target requests will not use the chosen server even while the client process is running.

In v2rayN, first choose rule-based routing in the routing settings or tray menu, then switch the system proxy to “Automatically Configure System Proxy” or the equivalent enable option in your version. After the switch succeeds, the tray icon or status bar will usually indicate that the system proxy is enabled. The connection is not complete yet because the active server has not been selected, but the traffic entry point is ready for the next step.

v2rayNG Mode Selection

v2rayNG takes over device traffic through the connection interface provided by Android, so the key controls are its in-app routing settings and connection switch. For a first setup, keep the default routing settings and complete the basic check first. When you tap the connection button, Android may display a connection authorization prompt; the client can create its local interface only after you approve it. Authorization only allows v2rayNG to handle device traffic; it does not prove that the remote server is reachable. Judge that separately from the connection state and actual access results.

If the app offers options such as “Bypass LAN,” “Domain Rules,” or predefined routing profiles, do not enable several overlapping rule sets during the first setup. Default rules reduce variables. After the connection is verified, adjust the direct-connection scope as needed. For the meaning of rule objects such as domain, ip, geosite, and geoip, see Routing and Traffic-Splitting Terms. Complex rule conflicts and DNS routing are outside this quick flow; use the Troubleshooting Handbook for those cases.

End State for This Step

The desktop client should use rule-based routing with the system proxy enabled. On Android, keep an explicit routing mode selected and be ready to approve the connection in the next step. Do not run another proxy client at the same time: multiple programs may compete for the same system proxy setting or local port. Close similar programs not involved in this test before selecting an active server.

routing-mode

Rule-Based Routing Recommended for first setup

Global Proxy For comparing routing rules

Direct Connection Traffic bypasses the active configuration

Next: Choose a Configuration and Connect →

CONNECT

Choose the Active Configuration and Connect

This stage has only two tasks: choose one active configuration from the subscription list, then start the client's connection entry point.

Choose an Active Server on Desktop

Return to the v2rayN server list, click the configuration you want to use, then choose “Set as Active Server” from the context menu, or use the shortcut available in your version. The active configuration is usually marked by a color, icon, font change, or status-bar text. Do not assume that a row is active just because the mouse has selected it. Mouse selection indicates interface focus; the active server is the target actually read by the core.

For the first selection, there is no need to run every server test repeatedly. Results depend on the current network, server response behavior, and test target, so they are only supporting data. Start with a configuration marked for general use by the provider, set it as the active server, and check the status at the bottom of the client. Confirm that the system proxy is still enabled. If switching modes caused the client to reload its configuration, wait for the status to settle before opening the browser.

Normally, v2rayN starts the selected core in the background and listens on a local proxy port. The log usually shows configuration loading, inbound listening, and startup messages. You do not need to change the port manually; it is enough to confirm that there are no messages about a port already being in use or a configuration parse failure. If a port conflict occurs, fully exit other similar clients and restart v2rayN. Do not change multiple local ports without knowing what they are used for.

Start the Connection on Android

In the v2rayNG main list, tap the server configuration you want to use to make it current. The interface usually marks the active item as selected. Then tap the connection button at the bottom. On the first start, Android may show a connection request. Approve it; a system connection indicator should appear in the status bar, and v2rayNG's bottom button should show a connected state. If authorization is denied, the app cannot take over device traffic; tap Connect again and approve the request.

A connection button showing an active state only confirms that the local connection interface was created; it does not by itself prove that the remote server works. Keep v2rayNG in the foreground for a few seconds and check for configuration errors, handshake failures, or repeated timeouts. If no obvious error appears, proceed to actual access testing. Avoid switching rapidly between multiple servers during the test; after each switch, give the client time to reload the configuration and establish the connection.

What to Do When Connection Errors Appear

If the log clearly reports a configuration parse failure, a field in the subscription is usually incompatible with the current client or core. Update the client subscription once, then test another configuration from the same subscription. If every configuration shows the same error, note the stage and keywords where it occurs, then see the client and configuration chapter in the Troubleshooting Handbook. For connection timeouts, switch networks or test another configuration first; do not immediately change DNS or routing.

Checkpoint Before Verification

v2rayN should show an active server, the system proxy should be enabled, and the log should not continuously report startup failures. v2rayNG should have a configuration selected and show that the connection has started. Once these conditions are met, client-side preparation is complete. Do not keep watching the button; use a new browser connection and changes in the logs to confirm that requests actually pass through the client.

connection-state

Active Configuration Selected
Local Proxy Running
Routing Mode Rule-Based
Next Verify with Actual Access

Next: Verify That the Connection Works →

VERIFY

Verify That the Proxy Is Really Working

Verification requires observing both actual access and the client logs. A connection icon, latency test, or local port alone cannot confirm the complete path.

Test with a New Browser Session

Close the test pages that have been open, then create a new browser tab and visit an ordinary site that should follow the proxy rules. Reopening the page reduces the influence of browser cache, existing connections, and DNS cache. If it loads, click another link on the site to make sure the result was not served only from local cache. On desktop, also test an ordinary direct-connection site to confirm that both types of access work under rule-based routing.

If the browser still shows the old network state, fully quit and reopen it. Some browsers keep established long-lived connections; when the system proxy changes afterward, existing connections may not switch immediately. Whether a desktop app follows the system proxy depends on its own implementation, so use a browser for the first check rather than relying on software with an uncertain proxy mechanism.

Watch the Client Logs at the Same Time

While opening a page, check the log area in v2rayN or v2rayNG. If new entries appear with the page request, traffic has entered the client. If the page still will not load, the likely scope is the remote configuration, routing match, DNS resolution, or the current network path. If the log does not change at all, the system proxy may not be active, the Android connection may not have started, or the test app may not use the current proxy entry point.

Interpret “connection established” and “request received” in the logs together with the page result. If requests appear but keep timing out, first switch to another configuration in the subscription. If access returns immediately, the original active configuration is temporarily unavailable. If every configuration times out, switch the device to another network for comparison. If only one category of domain fails while other access works, focus on DNS or routing rules rather than reinstalling the client.

Check the Desktop System Proxy

If v2rayN shows that it is running but the browser produces no log entries, return to the tray menu and check that the system proxy is still enabled. A network switch, an abnormal client exit, or another network tool may have overwritten the system proxy settings. Enable it again, then fully close and reopen the browser. If the setting changes back soon after being enabled, check whether another program is managing the same system setting.

Check the Android Connection Status

In v2rayNG, first confirm that the bottom button shows a connected state, then check the Android status bar for the corresponding connection indicator. If the connection stops soon after the app moves to the background, review Android's battery and background restrictions for v2rayNG. For a quick test, keep the app in the foreground and handle background persistence afterward. If only mobile data or only Wi-Fi fails, switch between them once and compare the results to determine whether the issue is network-specific.

Personalize the Setup After Verification

Once the basic connection is confirmed, you can enable scheduled subscription updates, adjust routing rules, or configure specific DNS settings. Change only one category at a time and repeat the access and log checks in this section afterward. This makes it clear which change caused a problem instead of leaving you to troubleshoot several changed parameters at once. For long-term management of multiple subscriptions, complex traffic splitting, TUN mode, or DNS policies, continue with the Troubleshooting Handbook rather than enabling every advanced option during first-time setup.

verification-path

1 Open a New Browser Session Exclude old connections and page cache
2 Watch the Client Logs Confirm requests enter the local proxy
3 Compare Another Configuration Separate a single-config issue from a global one
4 Check the Routing Result Confirm proxy and direct access behave as expected

BASIC CHECK

Basic Troubleshooting Order for First-Time Setup

Do not flip every switch at random. Narrow the scope based on the symptoms; this is usually faster than reinstalling or repeatedly importing the subscription.

A

Subscription Update Failed

Reopen the subscription settings, check that the URL is complete and contains no extra spaces, and confirm that the system time is correct. Then access the subscription URL directly on the current network. If the server returns an expired or denied message, resolve the subscription status first. If only the client request fails, inspect the network and certificate messages in the log.

B

Connected, but Websites Will Not Open

First check whether new log entries appear while opening the page. If there are none, check the desktop system proxy or Android connection status. If there are entries but they time out, switch the active configuration. If the result is unchanged, switch the current network for comparison, and only then check DNS and routing.

C

Only Some Sites Are Failing

This usually means the basic path is working; the issue is more likely routing, domain resolution, or the site's own status. Restore the client's default routing rules for comparison, then check which outbound direction the domain matched in the log. Do not delete the entire subscription because one site is having trouble.

D

Switching Servers Made No Difference

Confirm that the selected entry was set as the active configuration rather than merely focused in the interface. After switching, wait for the core to reload and reopen the browser connection. On Android, stop the old connection, select the target configuration, and start it again. On desktop, check the active server name in the status bar.

10-Minute V2Ray Client Setup