Use this guide if v2rayN shows no window when you double-click it, prompts you to install a runtime, exits immediately after launch, or opens normally but fails to start a core on Windows. First identify where startup fails, then check .NET, folder permissions, program files, and local ports. Change one thing at a time and keep the original folder and logs. This helps separate startup problems from subscription and connectivity issues.
First, distinguish an app crash from a core crash
v2rayN is the management interface; cores such as Xray handle connections. At startup, the app reads its settings, opens the local database, and initializes the interface. After you select a node, it generates a runtime configuration and starts the corresponding core. So “won’t open” and “can’t connect” are different problems. This guide checks the runtime, folder permissions, and core files in that order; the order does not indicate how likely each cause is.
After double-clicking, check the hidden icons area at the right end of the taskbar. Then press Ctrl + Shift + Esc to open Task Manager. If v2rayN is already running and its tray icon is visible, try opening the main window from the tray instead of repeatedly launching the app and adding variables to the diagnosis. If the process appears and then exits immediately, check the runtime and application logs.
| What you see | Check first | What to record |
|---|---|---|
| Prompt to install or update .NET | Runtime type, version, and architecture | Framework、Version、Architecture |
| No window appears; process exits quickly | Application errors, settings loading, write permissions | Exception details in Event Viewer |
| Main window works; core fails to start | Core files, runtime configuration, port | First error in the core log |
| Tray icon remains, but no window is visible | Hidden window, off-screen position | Whether an external display was just disconnected |
.NET Desktop Runtime: install what the package requires
The WPF interface on Windows depends on .NET desktop components. Installing only the .NET Runtime may not include the Windows Desktop Runtime, and having .NET Framework 4.8 installed does not mean modern .NET requirements are met. Self-contained packages typically include the runtime they need; framework-dependent packages require the matching runtime on your system. Check the package notes and the exact error message first.
Check the package architecture
Open Windows Settings → System → About and check System type. Then confirm whether the downloaded package is x64 or ARM64. The runtime architecture must match the program you are launching, not just your processor model.
Check the dependencies
If the program folder contains
v2rayN.runtimeconfig.json, open it in a text editor and check thenameandversionunderframeworkorframeworks. Do not change the version string to bypass a dependency.Install the runtime
On Microsoft’s .NET download page, choose the major version and architecture specified by the prompt. If the WPF package requires
Microsoft.WindowsDesktop.App, install the matching .NET Desktop Runtime—not just the ASP.NET Core Runtime.Restart and test
After installing, exit any existing process and launch the same program folder again. If the same prompt appears, compare the architecture and version in the error. Don’t install multiple unrelated major versions just to see if one works.
You can run the read-only PowerShell command below to list the runtimes visible to the .NET host that command resolves to. If PowerShell says “dotnet is not recognized,” that only means the command isn’t available; it doesn’t prove a self-contained package can’t run. Hosts for different architectures may also report different installed runtimes.
dotnet --info
dotnet --list-runtimesFor example, if the dependency entry says Microsoft.WindowsDesktop.App and 8.0.0, check for the matching architecture of the .NET 8 Desktop Runtime. A newer compatible patch in that release series will usually work. The version 8.0.0 is only an example; not every v2rayN release uses .NET 8. Check the requirements of your package, and don’t assume a newer major version can replace the required one.
Error: You must install or update .NET to run this application.
Cause and fix: The app can’t find a runtime framework that meets its requirements. Note the Framework, Architecture, and version shown in the prompt, then install the matching runtime. If it specifies the WindowsDesktop framework, make sure the Desktop Runtime is installed.
Folder permissions: test from a writable location
Extract portable packages fully before running them. Double-clicking the app inside an archive browser may extract only some files to a temporary folder. Protected folders, read-only media, and synced folders that restrict writes can also prevent settings, logs, or the database from being saved. Running as administrator is not a lasting fix; it can mask a folder permission problem.
Keep the original folder
Exit v2rayN from the tray and confirm in Task Manager that its processes have ended. Back up the original folder. Don’t delete settings files or move the database while the app is running.
Extract the package fully
Enter
%LOCALAPPDATA%in File Explorer’s address bar and create av2rayN-testfolder. Extract the same complete package there. Don’t copy your old settings for the first test.Check write access
Create a text file in the test folder, save it, and delete it. If that fails, open the folder’s Properties → Security and check your account’s permissions. Ask your administrator for help on a device managed by organizational policies.
Start with clean settings
Launch the app from the new folder as a standard user. If it opens, exit and launch it again to confirm settings persist before restoring subscriptions and routing rules.
Error: Access to the path '…' is denied.
Cause and fix: The process was denied access to a file or folder. Use the full path in the log to check your account’s read and write permissions and review security alerts. Retest from a folder you can write to instead of loosening permissions across an entire drive.
Error: The process cannot access the file because it is being used by another process.
Cause and fix: Another process has the target file open. Exit any duplicate instances and sync tools using the file, then relaunch the app. Don’t delete a database file that’s still in use.
If the new folder works but the old one doesn’t, the issue is likely tied to the old settings, files, or folder environment. Don’t copy everything from the old folder back at once—you could reintroduce the problem. Restore subscriptions first, then routing rules, and finally other settings, restarting to test after each step.
Missing or blocked core files: check the actual path
If the interface opens but the core exits immediately, check the main window’s log or information panel for the executable path and the first error. Folder layouts can vary by version and package type, so don’t create a core folder based on memory. A failed Xray configuration, a quarantined file, or an architecture mismatch can all appear as “core failed to start.”
- File is missing: Check the path in the log using File Explorer. If the download offers a complete package and other distribution options, follow its instructions to install any missing dependencies. Prefer extracting the complete package into a new folder; don’t mix files from different versions.
- File was quarantined: Open Windows Settings → Privacy & security → Windows Security → Virus & threat protection → Protection history. Look for the matching record around the time of the error. In Windows 10, find Windows Security under Update & Security.
- Windows blocked the app: First verify where the file came from and review the security alert. Only after confirming the file should you handle that specific item according to your security policy. Don’t disable protection for the whole device or exclude the entire download folder.
- The core starts but reports a configuration error: Keep the error field and line number, then check any recently changed routing, DNS, or node settings. Reinstalling .NET won’t fix a JSON syntax error in the core configuration.
If you use a custom full configuration, check that it supports your current core and version. V2Ray and Xray don’t necessarily support exactly the same fields. Review settings copied from another environment one by one rather than simply replacing the executable name.
Port conflicts and logs: pinpoint the cause
A busy local inbound port usually prevents the core from starting, but doesn’t necessarily close the management interface. The commands below use 10808 as an example; it isn’t guaranteed to be the default for every version. First check the actual local listening port in v2rayN under Settings → Parameter settings. The section names may differ between interface versions. Then replace the number in the command with the actual port.
netstat -ano | findstr ":10808"
tasklist /FI "PID eq 1234"In the first result, check that the Local Address column shows the target port and the status is LISTENING; the last column is the PID. The 1234 in the second command is only an example—replace it with the PID you found. Don’t mistake a matching remote port or a different connection state for a local listening conflict, and don’t terminate an unfamiliar system process.
Error: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.
Cause and fix: The address and port the core is trying to listen on are already in use. Identify the process using them, then exit any duplicate instance or choose an unused port in Parameter settings. Update the configuration of any apps that use the same port manually.
If the main app flashes and closes without leaving a usable client log, press Win + R, enter eventvwr.msc, then open Windows Logs → Application. Look around the time of the launch for entries from .NET Runtime or Application Error. Record the application path, exception type, and faulting module; an event ID alone won’t identify the cause.
- UnauthorizedAccessException: Return to the folder permission checks and use the exception path to identify the file.
- Settings or database read error: Retest with clean settings in a new folder. Keep the old database; don’t delete all user data.
- Native module error: Record the module name, system architecture, and client package type, then check the full package and system requirements. Don’t download a DLL with the same name from an untrusted site.
Restore settings and common questions
Verify the fix in two stages. First, open and close the app twice and confirm it saves settings, without importing a subscription. Then import a known-good configuration, start the core, and check the local port. If a website still won’t open, troubleshoot connectivity separately; that doesn’t mean the startup crash is still present.
Why does it still say a runtime is missing when .NET is installed?
Run dotnet --list-runtimes and compare the output with the startup prompt. Check whether Microsoft.WindowsDesktop.App is missing, whether the major version meets the requirement, and whether you chose x64 or ARM64 correctly. Having the SDK or another type of runtime installed doesn’t replace these checks.
It only opens when run as administrator. Can I keep using it that way?
First check that the folder is writable when launching as a standard user. TUN may require elevated permissions to create a virtual network adapter or change routes; that’s a separate requirement. Verify that the app starts in standard mode first so you don’t confuse the two permission issues.
It started crashing after an update. Should I overwrite the old folder?
Keep the old folder and exit all related processes. Extract the new package to a separate location. After confirming it starts with clean settings, reimport your subscription through the interface and restore rules gradually. If database migration is involved, don’t let different versions read and write to the same database.
There are no logs. What should I include in a report?
Include your Windows version and system architecture, v2rayN version, whether the package is Desktop or WPF, when the issue occurred, the exact prompt text, and any Event Viewer entry. Say whether the app exits before the window appears or fails after starting the core. Redact usernames in paths and connection credentials.