If v2rayN shows no window after you double-click it, first check whether its process is still running. Then check the runtime, complete extraction and write permissions, and user configuration—in that order. If the window opens but the proxy won't start, investigate the core and its ports instead. If an Android client stops after the screen locks, check background restrictions and VPN authorization. The steps below focus on Windows desktop, with repeatable checks and guidance on preserving subscriptions and existing settings.
1. Distinguish a Hidden Window, an App Crash, and a Core Exit
“Crashes on startup” can describe three different situations: the main window is minimized to the notification area, the GUI process has actually exited, or the GUI is still open but the core failed to start. v2rayN is the graphical client; V2Ray and Xray are connection cores. Subscriptions store server details, while routing rules determine which outbound connection is used. Problems that occur before the GUI opens usually won't be fixed by updating a subscription or switching VMess or VLESS servers.
- No window, but the process is running: Press
Ctrl + Shift + Escto open Task Manager, findv2rayN.exeunder “Details,” then check the taskbar notification area and try opening the main window from its tray icon. Avoid double-clicking repeatedly, which can trigger multiple launch attempts. - The process appears, then disappears: Note when it happens and check the runtime, permissions, and configuration in the order below. If an error dialog appears, record its full text—not just “it won't open.”
- The main window opens, but starting the proxy fails: Check the client's log area. This points to a core startup failure, which requires a different troubleshooting path from a GUI crash.
2. .NET Runtime: Check the Requirement, Then Install the Matching Architecture
The classic WPF and desktop versions of v2rayN for Windows may use different UI technologies and packaging, so don't assume every package needs the same runtime. Framework-dependent apps require the relevant runtime to be installed; self-contained packages usually include the runtime they need. If you see “You must install or update .NET to run this application,” check the Framework, Version, and Architecture shown in the dialog. Don't install a component just because its name contains .NET.
Error: You must install or update .NET to run this application.
Cause and fix: The required shared .NET framework is missing or doesn't meet the app's requirements. Note the framework name, required version, and architecture shown in the dialog, then install the matching runtime from Microsoft.
Error: You must install .NET Desktop Runtime to run this application.
Cause and fix: The app requires the Windows Desktop Runtime. For a WPF package, check for .NET Desktop Runtime—not just ASP.NET Core Runtime or an older .NET Framework.
Run the command below in Command Prompt or PowerShell to list the shared runtimes visible to the dotnet host currently being invoked. WPF typically requires an entry named Microsoft.WindowsDesktop.App. Seeing only Microsoft.NETCore.App doesn't mean the desktop framework is installed.
dotnet --list-runtimes
where.exe dotnet- Check the architecture: In Windows, go to Settings → System → About and check the system type, then compare it with the requirement in the app's dialog. An x64 app needs the matching x64 runtime; an x86 runtime is not a substitute.
- Check the framework: If the extracted folder contains
v2rayN.runtimeconfig.json, open it read-only in a text editor to check the required framework and version. Don't edit it to force the app to use an incompatible runtime. - Complete the installation: Get the required runtime from an official Microsoft source, close any running client processes, and then launch the app again. Installing a later major version doesn't necessarily satisfy a requirement for an earlier one.
If Windows says it can't find the dotnet command, that only means the current command search path didn't locate it; it doesn't prove that no runtimes are installed. Conversely, this command alone can't tell you whether a self-contained package can run. Use the startup dialog, package documentation, and runtime configuration file as your main references.
3. Extract All Files and Check Folder Permissions: Test in a Writable Location
Double-clicking the app inside an archive preview may extract only the executable temporarily, leaving its libraries, core, and resource files behind. Extracting the program to a protected folder can also prevent it from creating logs, saving settings, or generating core configuration. Start by extracting all files and testing in a writable folder; don't treat “always run as administrator” as the default fix.
-
Exit the process
Quit v2rayN from the tray menu, then use Task Manager to confirm the old process has ended. If TUN or an additional service is enabled, turn it off in the client first so leftover services aren't mistaken for a duplicate app process.
-
Extract all files
Use your archive utility's “Extract All” option to unpack the entire package into a new, empty folder. Don't copy only
v2rayN.exe, and don't merge or overwrite it directly into an existing installation. -
Test write access
For the test, use a local folder your current user can write to, such as
%LOCALAPPDATA%\V2RayN-Test. Create and delete a plain text file in the target folder to confirm that basic write access works. -
Launch normally
First launch as a standard user, without importing old settings or enabling TUN. Once the blank window opens, restore settings one at a time. Handle any elevation required for TUN separately.
If moving the app restores normal operation, check the original folder's Properties → Security permissions for your user. Also check Windows Security → Virus & threat protection → Protection history for a related block. Don't disable your entire security suite just to launch the app, and don't copy individual DLLs from unknown sources. Ask your administrator to review access controls on a managed device.
4. Corrupt Configuration Files: Back Up and Isolate, Don't Delete
If the crashes began after changing settings, an unexpected shutdown, or an update—and the same package opens with an isolated configuration—focus on the user configuration. A truncated file, invalid field type, damaged data file, or failed migration from an older setting can make the app exit while loading preferences. A temporarily unreachable subscription server usually causes an update failure; don't assume that means the local configuration is corrupt.
- Back up first: Fully exit the app, then copy the entire old program folder and the user data folder actually used by that installation. Preserve the folder structure. Store the backup somewhere private, not in a publicly shared or automatically synced location.
- Find the right location: A portable package may store configuration beside the program; an installer or another package type may use a user data folder. Some versions have
guiConfigsandguiNConfig.json, but don't assume every version uses the same layout. - Isolate by renaming: Once you've found the configuration the app actually reads, rename the relevant folder to keep it—for example, add a
.backupsuffix—then launch the app and see whether it creates a fresh configuration. If you're unsure where the data is, check the path in the error log first. Don't search for and delete every file with the same name. - Restore items one at a time: Start with one trusted subscription or server and check that the app launches. Then restore routing, DNS, and other options. Don't overwrite everything with the old configuration at once, or you won't know which item triggered the problem again.
Error: System.Text.Json.JsonException
Cause and fix: The JSON reader encountered a syntax or type error. Check the full log for the file path, back up the file, then isolate that configuration. Don't delete every JSON file based only on the exception name.
Error: System.UnauthorizedAccessException
Cause and fix: Access to a file or folder was denied. Check read/write permissions and security software logs for the path named in the exception. Fix the access issue instead of treating the configuration as corrupt.
If the app still crashes from a newly extracted folder, that doesn't rule out a configuration issue: both launches may be using the same user data folder. To confirm the fix, make sure the app opens with an isolated configuration—not merely from a different program folder.
5. GUI Opens but the Proxy Fails: Check the Core and Ports
If the main window stays open, shift your focus from .NET to the core. v2rayN's system proxy toggle lets apps that respect the system proxy use a local entry point. Routing rules then select an outbound connection after traffic reaches the core. If the core hasn't started, the local listening port may not exist; switching between global and bypass-mainland-China modes usually won't help.
Open Settings → Parameter Settings and check the local listening address and port shown in your version. The example below uses 127.0.0.1:10808; this is not a fixed value, so replace it with your actual configured port. After running the command, check the local address, whether the state is LISTENING, and the PID in the last column.
netstat -ano | findstr ":10808"
tasklist /FI "PID eq 2468"The 2468 on the second line is only an example PID argument; replace it with the number shown on the first line. A connection to a remote address using that port doesn't prove the port is occupied locally. Once you've identified the process, exit it from its own interface or change the listening port in the client. Update any apps where you manually entered the proxy address as well.
Error: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.
Cause and fix: Another process is using the local address and port. Identify the program from its PID, then stop the duplicate instance or choose an unused port. Don't kill a system service based on its process name alone.
Error: The system cannot find the file specified.
Cause and fix: A requested file doesn't exist. Check the core, resource, or configuration path named in the log, then extract the full package again. Don't assume every missing file is a runtime issue.
6. Android Background Shutdowns: Check v2rayNG and v2flyNG Permissions
Android clients such as v2rayNG and v2flyNG don't use the Windows .NET Desktop Runtime. v2rayNG uses the Xray core; v2flyNG uses the V2Fly core. If the app connects in the foreground but stops after the screen locks or you switch apps, check battery restrictions, background operation, and VPN authorization first. If the app exits as soon as you open it, troubleshoot it as an app crash instead of assuming a battery-saving setting is responsible.
- Check background restrictions: On Android, go to Settings → Apps → the relevant client → Battery and check whether background use is allowed or an “Unrestricted” option is available. Menu names vary by manufacturer, so use the options shown on your device and monitor battery use after changing them.
- Restore VPN authorization: Tap Connect in the client again, read the system VPN connection prompt, and confirm it. If another VPN service is running, decide which one you need to keep before stopping the conflicting service.
- Check for permission revocation: In the app info page, review settings related to unused apps. Permission revocation and background restrictions are separate controls. Restore only the permissions the app actually needs; don't grant every permission just to troubleshoot.
- Distinguish the UI from the service: A missing notification doesn't necessarily mean the process crashed, and notification permission is not the same as VPN authorization. Check the client's connection status, try accessing a site, and review the system's app information.
Before reinstalling, make a private backup of your subscription source and any essential settings. Then go to the download center and choose the installer for your device architecture. Don't clear app storage before finding your subscription URL; this can erase local servers and app settings, and won't necessarily fix a background shutdown caused by system policy.
7. Common Questions and Troubleshooting Notes
Why does it still say a runtime is missing after I installed .NET?
Check the framework name, major version, and architecture in the dialog again. WPF needs the Desktop Runtime, not ASP.NET Core Runtime, and x64 and x86 runtimes aren't interchangeable. Use where.exe dotnet to see which executable the command points to, then compare with the results of dotnet --list-runtimes.
It opens when run as administrator. Should I always do that?
First test as a standard user in a writable folder. If only the old folder is unwritable, fix its permissions or move the app. Handle elevation for features such as TUN separately. Running the entire app with elevated privileges long-term can hide an access issue you could otherwise identify and fix.
Will changing servers or updating my subscription fix a startup crash?
If the app hasn't opened its main window, troubleshoot the runtime, files, and configuration loading first. Check the subscription URL, network, and server settings only if the GUI opens and then reports a subscription update or specific server connection failure.
Where can I find logs if no error dialog appears?
Press Win + R, enter eventvwr.msc, then go to Windows Logs → Application. Look around the time of the crash for Application Error or .NET Runtime events, and note the application path, exception details, and time. Not every crash generates both types of event.
If you need further help, provide your system type, package type, whether you tested with an isolated configuration, the conditions of the last successful launch, and the error details from the relevant time. Redact subscription links, server addresses, user IDs, and credentials in logs; keep the error type, file names, and port details needed to diagnose the issue.
- Runtime findings: Record the required framework name and architecture, and whether the same prompt still appears after installation.
- File and configuration findings: Record the results of testing a new folder and an isolated configuration separately, so the two variables aren't confused.
- Core findings: Record whether the main window stays open, whether the listening port is established, and the earliest error in the log. Later cascading errors are usually less useful than the first one.