Before using v2rayN for the first time, check the package architecture and make sure its folder is writable. Then confirm the core starts and the local port is listening. Finally, import a subscription and configure the system proxy. This guide walks Windows and macOS users through the setup in order: launch the app, start the core, connect to a node, then configure apps. Changing one setting at a time makes it easier to identify the cause of a problem.
Package and Extraction Location: Check Architecture and Write Access First
v2rayN is a configuration interface; the selected core handles the actual connection. Opening the main window only confirms that the interface launched—it does not mean the core files are complete or that a node is usable. When downloading, check the operating system, processor architecture, and package notes. For Windows, don’t assume that a filename containing x64 is enough to identify whether the desktop or classic WPF build suits your system.
Check Installation Locations on Windows and macOS
Windows
- Open Settings → System → About and check the system type to distinguish x64 from ARM64.
- Extract the entire archive to a folder you can write to, such as
C:\Users\Public\Tools\v2rayN, and check the folder’s actual permissions. - Keep the dependencies and core folders alongside the main program. Don’t drag only the executable to the desktop.
- Make sure shortcuts point to the extracted program, not a temporary file in the archive preview.
macOS
- Open the Apple menu → About This Mac and check whether your Mac has an Apple chip or an Intel processor.
- Extract the package or open the disk image, then move the app to a stable location such as Applications.
- Don’t run the app long-term from a read-only disk image or temporary extraction folder.
- If the log says a configuration folder isn’t writable, check the specific folder named in the log. Don’t broadly loosen permissions across your home directory.
Choose a stable location for the program and its configuration before importing a subscription. Back up your settings before upgrading, and avoid switching between old and new folders.
Portable packages typically save settings or related data in their own folder. If settings disappear after every launch from a protected location, first check for write failures and make sure you haven’t launched a different copy. Adjust permissions only if needed. Keep the path short and avoid temporary folders that may be cleared automatically. Non-ASCII characters in a path are not inherently a problem; there’s no need to reinstall your operating system just because a folder name contains them.
First Launch: Check Runtime Requirements, Security Prompts, and TUN Permissions
If Windows reports a missing runtime, follow the prompt and match the framework name, major version, and architecture. Packages that rely on a system runtime have different requirements from self-contained packages. The classic WPF interface may require the corresponding Windows Desktop Runtime; installing a different major version at random won’t help. If a self-contained package still won’t launch, check the error log before installing multiple runtimes.
-
Keep the Original Error
Save the startup prompt, Windows version, and package name. If the window closes immediately, check the app log or Windows application error records to distinguish a missing runtime from missing files or an architecture mismatch.
-
Check Permission to Launch
If Windows blocks the app, first check Windows Security → Virus & threat protection → Protection history. Only take action after confirming the source and the blocked item. Don’t disable your entire security suite.
-
Handle System Prompts
On macOS, if an app from a verified source hasn’t yet been approved to run, check the specific prompt under System Settings → Privacy & Security and follow the system’s steps to approve it. If macOS says the app is damaged, download the package that matches your architecture again.
-
Leave TUN Off for Now
Start with a regular local proxy. TUN requires a virtual network device, routing, and additional permissions, so configure it separately after confirming the regular proxy works. If prompted, grant the permissions required by the client.
Import a Subscription and Select a Core: Start with One Verifiable Configuration
A subscription URL retrieves a list of nodes; it is not a node server address or a browser proxy address. Subscriptions may contain authentication tokens, so don’t share the full URL when troubleshooting. Button locations can vary between versions. Look for features such as Subscription Group Settings and Parameter Settings, and follow the labels shown in your current interface.
-
Add a Subscription Group
Go to Subscription Group → Subscription Group Settings, add a group, and enter a recognizable name and the full subscription URL. Check for spaces at either end, save, and return to the main window.
-
Update the Node List
Choose Update from the Subscription Group menu. If no nodes are available yet, try updating without a proxy first. If your provider requires a proxy, you’ll need an existing working connection—you can’t use nodes that haven’t been imported yet.
-
Check the Core Type
Go to Settings → Parameter Settings → Core Type and check which core is used for the relevant protocol. VLESS, REALITY, and XTLS Vision configurations require an Xray core that supports this combination. Don’t switch cores based only on similar names.
-
Select an Active Node
Select a node and set it as the active server. Check the log for configuration parsing errors or a core that has exited. After switching cores, restart the core as prompted and confirm that the old process is no longer running.
VMess and VLESS are proxy protocols; Xray and V2Ray are core projects; v2rayN manages configurations and starts the core. These are separate layers and can’t replace one another. Successfully importing a subscription only confirms that its contents can be read. Whether a node connects also depends on its protocol parameters, transport, TLS settings, and server status.
- Core not found: Check whether the package includes the required core and whether security software quarantined it. Don’t copy in a file for a different architecture just to fill the folder.
- Unknown field or invalid configuration: Check the node’s requirements against the core’s capabilities. Keep the original error and update the core using a method supported by the client.
- TLS error: First sync your system date and time, then check settings such as the server name. Don’t disable certificate verification as a routine fix.
Local Listening Port: Match 127.0.0.1 and the Actual Port
This example uses 10808 as a local SOCKS port or a mixed port that supports SOCKS, and 127.0.0.1 as the address of the current device. These aren’t fixed defaults across all builds. Go to Settings → Parameter Settings and check the local listen address, port, and inbound protocol. Then update the values in the test commands to match your configuration.
| What to Check | How to Verify | Common Mistake |
|---|---|---|
| SOCKS and HTTP Inbounds | Set the app’s proxy type to match the inbound protocol. A mixed inbound can accept the protocols it supports. | Entering a SOCKS-only port in the app’s HTTP proxy field. |
| Separate HTTP Port | If you configure port 10809, first confirm that it’s actually listening. | Assuming port 10809 is enabled because it appears in an old guide. |
| Listen Address | For local use, check 127.0.0.1 first. Sharing with devices on your LAN is a separate setting. | Opening the listener on every network interface just to troubleshoot, expanding who can access it. |
| Port Conflict | Identify the process using the port by its process ID, then close the duplicate instance or choose another port. | Changing the app’s port without updating the core’s listening settings. |
Windows: Check the Listener and the Process Using the Port
Get-NetTCPConnection -LocalPort 10808 -State Listen |
Select-Object LocalAddress, LocalPort, OwningProcess
Test-NetConnection -ComputerName 127.0.0.1 -Port 10808Run the commands above in PowerShell. If the first command returns nothing, check whether the core is running and whether the port is correct. If a process ID appears, identify the process in Task Manager; don’t end an unfamiliar system process. A successful response from the second command only confirms that the local TCP inbound is reachable, not that the remote node is connected.
macOS: Check Listening Sockets
lsof -nP -iTCP:10808 -sTCP:LISTENThe process name and PID in the output can help identify the listener. If there’s no output, first check the v2rayN log for core startup errors. If you changed the listening port, restart the core and run the check again. Don’t test the old port while deciding whether the new setting has failed.
System Proxy and Routing: Verify the Inbound Before Checking the Outbound
The system proxy tells apps that support it to send requests to the local inbound. Routing determines which outbound handles requests once they reach the core. Switching routing to global won’t make an app that ignores the system proxy connect automatically. For your first test, leave TUN off, select Set system proxy automatically from v2rayN’s System Proxy menu, then check that the operating system shows the corresponding proxy settings.
- Windows: Open Settings → Network & Internet → Proxy and check the active proxy settings. If your browser still points to a local port that’s no longer running after you quit the client, restart the client and select Clear system proxy to restore your settings.
- macOS: Open System Settings → Network → your current network service → Details → Proxies and check which settings are active. Check again after switching network services; don’t rely only on the client’s button state.
- Browsers and command-line tools: A browser may be affected by its own proxy extension, while command-line tools may not use the system proxy. Specify the proxy explicitly when testing to avoid uncertainty about the inbound.
The commands below require 10808 to provide SOCKS service. In Windows PowerShell, use curl.exe; in the macOS Terminal, use curl. The socks5h scheme sends the destination hostname to the proxy for resolution, which helps distinguish local DNS issues from proxy connection issues. It does not change your system DNS settings.
# Windows PowerShell
curl.exe --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.com
# macOS Terminal
curl --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.comCommon First-Run Issues: Narrow Down the Cause
The window opens, but selecting a node causes an error. Why?
Check the first error that appears after enabling the node. If a file is missing, check the core location. If configuration parsing fails, verify the protocol and Core Type. If the port is in use, check the listening process. Don’t assume all three errors mean the subscription is invalid.
A subscription update timed out. Should I enable updates through the proxy?
If you already have a working node that can reach the subscription URL, choose Update via proxy from the Subscription Group menu. When the node list is empty, enabling this option won’t create a connection. First check that the URL is valid, the network can reach it, and the service hasn’t expired.
The latency test shows a number, so why won’t websites load?
First check whether you ran a TCP latency test or a real connection test. A reachable port doesn’t mean the protocol handshake succeeded. Test with an explicit proxy command, then check the system proxy, browser settings, and routing log. Don’t judge the connection by a latency number alone.
Why do I have to import the subscription again after restarting? Did it fail to save?
First make sure you didn’t launch a different copy of the program, then check whether the configuration folder is writable. Keep the shortcut or app location consistent, quit and reopen to verify, and back up your settings before moving folders. Don’t run old and new copies at the same time.
Post-Setup Checklist
The goal of a first-time setup is a connection path you can verify repeatedly, not turning on every feature at once. Test after each change so that if something fails, you can trace it to the setting you just changed. Add TUN, autostart, or more complex routing one at a time after the basic connection is stable.
- App: The app launches normally, and subscriptions and settings remain after you quit and reopen it.
- Core: Enabling the active node produces no configuration parsing errors, and the local port is listening.
- Connection: An explicit proxy test receives a response, and the routing log confirms which outbound was used.
- Apps: The target app uses the correct proxy, and browser and command-line test results can be explained separately.
- Restore on exit: Select Clear system proxy before quitting the client, then confirm that regular network requests no longer rely on the stopped listening port.
If you need to troubleshoot further, note your operating system and architecture, v2rayN version, core name and version, inbound port, and the first error in the log. Before sharing screenshots, hide subscription tokens, node credentials, and private server settings. The full error context is more useful for finding the cause than repeated reinstalls or frequent core switches.