For Windows and macOS users trying v2rayN 7.x for the first time. Follow the checks in order: runtime, core selection, subscription import, system proxy, routing, automatic updates, and connection testing. This helps prevent common issues such as a selected node that cannot load websites, an empty node list after importing a subscription, or a proxy that stops working after reboot.
Check your system, architecture, and runtime before installation
Do not start first-run setup by pasting a subscription URL. First make sure the download matches your device architecture, then determine whether you have a self-contained package or one that requires a runtime. The wrong architecture can prevent the app from launching; a missing runtime usually produces a .NET component error, not a node configuration error.
The v2rayN 7.x desktop release supports Windows, macOS, and Linux. Most Windows PCs use the x64 package, while ARM-based devices need arm64; macOS also has separate arm64 and x64 builds. Do not rely on a filename that merely says “desktop.” Check your processor architecture in system information before downloading.
Windows prerequisites
- Common architectures
- x64
- Working directory
- User-writable directory
- Runtime
- .NET 8 Desktop Runtime or a self-contained package
- Local proxy address
- 127.0.0.1
Do not keep it long-term in an archive preview window or in a system directory that requires administrator permission to write.
macOS prerequisites
- Common architectures
- arm64 or x64
- Application location
- A fixed application directory
- Runtime
- .NET 8 Runtime or a self-contained package
- Menu location
- Top menu bar
Keep the application path stable after the first launch so the login item does not continue pointing to a location that has been moved.
- Run the main program only after extraction is complete, so configuration files, logs, and core files can be written normally.
- Quit the running v2rayN process before upgrading, and make sure the process shown in the menu bar or system tray has ended.
- Keep backups of your subscription URLs and any custom routing rules. When migrating, do not copy only the executable file.
- If the app opens but the core fails to start, check file paths, permissions, and runtime messages in the log before reviewing node parameters.
Complete the basics in a fixed order on first launch
The reliable order is: confirm the core, add a subscription, choose a server, then enable the system proxy. If you keep toggling the system proxy from the start, issues become mixed together: the core may not be running, the subscription may not have updated, or the browser may simply have ignored the new proxy settings.
-
Confirm the core
Open “Settings” → “Parameter Settings” → “Core Type,” then select Xray for standard VLESS and VMess nodes. Save, return to the main window, and check the bottom log for a successful core-start message.
-
Add a group
Go to “Subscription Groups” → “Subscription Group Settings” → “Add.” Enter an easy-to-recognize alias and paste the complete subscription URL. Do not leave spaces or line breaks before or after the URL.
-
Update the subscription
After saving the group, choose “Subscription Groups” → “Update All Subscriptions.” Wait for the node list to refresh and make sure the result is not a timeout, empty content, or a format-parsing failure.
-
Choose a node
Select a node in the server list and set it as the active server. A highlighted row only identifies the current target; you must still confirm that the core is running.
-
Set up routing
For the first test, choose a basic routing mode with clear rules. Once the connection works, adjust custom rules for your LAN, direct destinations, and proxied destinations.
-
Enable the proxy
Open “System Proxy” from the system tray or menu bar and choose automatic system proxy configuration. After testing or before quitting, switch to clear system proxy settings so the system does not retain a dead port.
Check the main-window status and logs after each step. Troubleshooting is much more direct this way. For example, if subscription updating already failed, there is no need to change routing; if the core is not listening on its port, the browser cache is not the first suspect.
Keep system proxy, core ports, and routing modes separate
“Node connected” does not mean every app is using the proxy. The core listens on local ports and communicates with the remote server; the system proxy directs apps that follow the operating system proxy settings to those local ports; routing rules then decide whether each request exits through the proxy or directly. If any one of these layers is missing, some programs may work while others fail.
Two proxy approaches for first-time testing
Everyday rule mode
- Use automatic system proxy configuration
- Connect common local destinations directly according to the rules
- Send other matching requests through the proxy
- Best for regular use after basic verification
Temporary global test
- Send the target traffic through the proxy for a short time
- Use it to determine whether routing rules are the cause
- Restore everyday routing after testing
- Do not treat the test state as a permanent configuration
Global mode helps narrow the scope of a failure. Once the node and core are confirmed to work, return to rule mode and inspect routing matches one by one.
| Check | Common value | How to verify |
|---|---|---|
| Listen address | 127.0.0.1 | When only local programs need access, use a loopback address. Do not enter the address of a remote server by mistake. |
| SOCKS port | 10808 | Compare the actual port in Parameter Settings with the core log. Any app configured manually must use the same port. |
| HTTP port | 10809 | Some versions or configurations use a separate HTTP port. Follow the value shown in the interface and the port reported as listening in the log. |
| Port conflict | address in use at startup | Quit the old process or change the local port to an unused value, such as changing 10808 to 10818. |
Do not copy port numbers blindly. 10808 and 10809 are common defaults, but user changes, migrations from older versions, and other local services can alter them. The most reliable sources are the local listener settings under “Settings” → “Parameter Settings” and the actual listen address reported in the core startup log.
Check protocol fields and update results after importing a subscription
A subscription is more than a list of node names. Each entry can include a server address, port, user ID, transport, TLS settings, path, Server Name, Reality public key, fingerprint, and other fields. After updating a subscription, v2rayN converts these values into a local configuration; a missing key field can cause the handshake to fail.
For VMess and VLESS, do not compare only the server address. The same address can use different ports, transports, and security layers. When editing a node manually, take particular care not to copy fields from one protocol into another.
VLESS + Reality
- Protocol
- VLESS
- Transport
- TCP
- Flow
- xtls-rprx-vision
- Fingerprint
- chrome
- Required fields
- Public key and Server Name
These fields are normally populated automatically by the subscription. Before editing them manually, compare each value with the original parameters provided by the subscription.
VMess + WS + TLS
- Protocol
- VMess
- Transport
- WebSocket
- Path
- Specified by the subscription
- Encryption
- auto
- Required fields
- Host and Server Name
Whether the path includes a slash and whether Host is correct both affect the WebSocket handshake. Do not infer them from the node name.
- Zero nodes after an update: first check whether the subscription response is empty, then make sure the URL was not truncated by a line break.
- Old nodes are still present: check whether you updated a different subscription group and whether the group is configured to remove old records.
- Node names look normal but every node fails: prioritize checking subscription validity, system time, core type, and handshake errors in the log.
- Only a few nodes fail: compare them with other nodes in the same group to determine whether the issue is limited to those nodes or caused by a shared local setting.
Configure startup, subscription updates, and saved settings
Enable automation only after the basic connection works. This prevents the app from loading an unverified configuration immediately at every login. Windows and macOS use different login-start mechanisms, but the checks are the same: the app path must remain stable, the login item must exist, and the core and local listening port must work after startup.
- Enable startup: Open “Settings” → “Parameter Settings” and find the option to start automatically at login. On Windows, also check the system startup-app list; on macOS, check that the login item points to the current application location.
- Keep the path fixed: Do not move the application directory after enabling login startup. If it has already been moved, remove the old login item first, then enable startup again from the new location.
- Set the update interval: Enter an automatic update interval in Subscription Group Settings based on your needs. For a personal device, start with 1440 minutes—once a day. There is no need to send requests every few minutes.
- Keep startup logs: After rebooting, first check whether the core started automatically, then confirm that the subscription update succeeded. Successful startup and successful updating are independent results.
- Test the quit behavior: Closing the main window may only minimize the app to the system tray or menu bar. To stop the proxy completely, choose Quit from the app menu and confirm that the system proxy has been cleared.
| Item | Suggested starting value | When to review |
|---|---|---|
| Automatic subscription updates | 1440 minutes | When nodes remain unchanged for a long time or updates repeatedly fail |
| Start automatically at login | Enable after the basic connection works | After moving the application directory or upgrading to a major version |
| System proxy status | Automatic system proxy configuration | After every abnormal exit or system reboot |
| Configuration backup | Once before a major change | Before changing custom routes, groups, or ports |
More frequent automatic updates are not always better. A short interval can quickly fill the error log and repeatedly trigger requests as soon as the network recovers. Once a day is usually enough for a device that is not online around the clock; when you need changes immediately, manually choosing “Update All Subscriptions” is clearer.
Use reproducible tests to confirm that the setup works
Do not judge the first connection only by a color or latency number in the server list. A complete check should cover core startup, local port listening, system proxy behavior, target webpage access, and a repeat test after switching nodes. Change only one variable at a time so you can tell whether the result comes from the node, routing, or local configuration.
| Test step | Example record | What it means |
|---|---|---|
| Core startup | 127.0.0.1:10808 is listening | The local SOCKS entry point is available, but this alone does not prove that the remote handshake succeeded. |
| Actual connection latency | 186 ms | The sample value includes a proxy-protocol handshake, making it closer to a real connection than a simple network probe. |
| Retest with a second node | 241 ms | Compare on the same device and under the same routing mode to determine whether the difference is concentrated on the node side. |
| Disable the system proxy | The target request returns to a direct connection | This confirms that the browser was actually reading the system proxy rather than using a separate proxy setting. |
| Restart the app | The active node and group are still present | This indicates that the configuration was saved in a stable directory rather than left in a temporary extraction location. |
The 186 ms and 241 ms values in the table are examples from one troubleshooting record, not speed benchmarks. Latency depends on node location, network route, time of day, and handshake method. What matters here is recording the test conditions: the same network, target, and routing mode, with the node as the only change before and after switching.
- Test one node first, then test the full list after it works. This prevents a flood of failures from hiding the first error.
- After switching nodes, reopen the test page to reduce false conclusions caused by reused connections.
- If rule mode fails but a temporary global test succeeds, focus on routing matches for the domain, IP, and outbound tag.
- If two nodes fail at the same time, check the local network, subscription status, and core log first. Do not keep changing protocol fields in succession.
Common first-use problems and the troubleshooting order
The basic troubleshooting principle is to check layer by layer from the local machine outward: start with the app and core, then ports and system proxy, followed by the subscription and node, and finally routing and transport parameters. Skipping the foundational layers often leads to mistaking a port conflict for a failed node.
Does the subscription update keep timing out?
First confirm that the subscription URL is complete, then open Subscription Group Settings and check the update method. If the current network needs an existing proxy to reach the subscription, connect to a working node first, enable “Update Subscription Through Proxy,” and retry. If it still fails, check the log for DNS resolution errors, connection refusals, or timeouts.
The node is selected, but webpages will not load?
First check the core log to confirm that a local port such as 127.0.0.1:10808 is listening, then make sure “System Proxy” is set to automatic configuration. If the port is occupied, quit the old process or change the port under “Settings” → “Parameter Settings,” then restart the core.
Rule mode fails, but the global test works?
This usually points to a routing-match problem. Open Routing Settings and check whether the target domain or IP is being matched early to the direct outbound, then review rule order. After making changes, close the old connection and retest the target with the same node.
Does the proxy stop working completely after a reboot?
Confirm that v2rayN appears in the system login items and that the app is still in the directory used when startup was enabled. After launch, also confirm that the core started, an active server exists, and the system proxy was written again. Do not check only whether the main window opened.
Does the browser lose network access after quitting the app?
The system may still be pointing its proxy settings at a local port even though the core has stopped. Reopen v2rayN, choose Clear System Proxy under “System Proxy,” and quit normally. Then check the operating system’s network settings for any remaining 127.0.0.1 entry and old port.
After these checks, you should be able to answer five questions clearly: Is the app running from a stable directory? Did the core start successfully? Did the subscription update normally? Is the system proxy pointing to the correct port? Is routing selecting the expected outbound? When connections change later, follow the same order to locate the cause quickly.