This guide is for cases where the v2rayN window disappears after launch, the app won't open after an update, or the interface appears but the core exits immediately. First determine whether the interface or the core is exiting, then preserve the logs and check runtimes, write permissions, user data, and listening ports in order. The steps focus on Windows, with terminal checks for Linux. Don't start by deleting the entire data directory.
First, tell an interface crash from a core exit
v2rayN is the client interface; the core it launches handles proxy connections. A failed interface launch is different from a failed Xray or other core launch. VMess and VLESS are connection protocols, and subscriptions provide configuration. Before a connection attempt, changing subscriptions or protocols usually won't fix an interface crash.
| What you see | What to check first | Evidence to keep |
|---|---|---|
| The window never appears and the process disappears | Runtime, package architecture, startup errors | System alerts and Event Viewer entries |
| The window closes, but the tray icon remains | Whether the app was minimized to the tray | Process status in Task Manager |
| The interface is open, but the log repeatedly reports startup failures | Core files, generated config, listening ports | Full core error message |
| The interface and core work, but websites won't load | System proxy, routing rules, DNS, and node | Connection logs and app proxy settings |
Press Ctrl + Shift + Esc to open Task Manager and check whether a v2rayN process is still running. If the app is only in the tray, double-click its icon to restore the window. If it has exited, note the time, then press Win + R, enter eventvwr.msc, and go to “Windows Logs” → “Application.” Check for a “.NET Runtime” or “Application Error” entry at the same time. Record the faulting module, exception type, and file path.
.NET runtime: match the framework and architecture in the error
If an alert asks you to install .NET, check the full message for the framework name, required version, and architecture. Packages that depend on an external runtime work differently from self-contained packages. Don't assume every v2rayN package requires the same .NET major version, or that installing a newer major version will always make an older program compatible.
You must install or update .NET to run this application.
Cause: The program can't find the .NET runtime it needs. Fix: Install the runtime that matches the framework, version, and architecture specified in the alert, then relaunch the app. If you're using a self-contained package, download and fully extract a package that matches your system.
Run the following command in PowerShell to see which runtimes are visible to the available dotnet host. If you see a message that the dotnet command cannot be found, that only means it is unavailable in the current command environment; it does not prove that runtimes for all architectures are missing. Also check Installed apps in Windows and review the error dialog.
dotnet --info
dotnet --list-runtimes- If the alert requires
Microsoft.WindowsDesktop.App, install the matching Windows Desktop Runtime. The standard .NET Runtime and ASP.NET Core Runtime are not substitutes. - If the alert requires
Microsoft.NETCore.App, follow that framework's requirements; don't assume it also needs the desktop framework. - The package architecture must match: x64, x86, or ARM64. An architecture supported by your operating system isn't necessarily the one used by the package you downloaded.
- When upgrading, don't just overwrite the main program. Fully extract the package to a new folder to avoid mixing old dependencies with new files.
On Linux, open a terminal in the extracted folder and launch the program there to see any errors. If you get Permission denied, check execute permissions. If a shared library is missing, install the specific dependency. Don't apply Windows Desktop Runtime installation steps on Linux.
cd ~/Applications/v2rayN
ls -l ./v2rayN
chmod u+x ./v2rayN
./v2rayNThe Linux commands below assume the program is located in ~/Applications/v2rayN. Add execute permission only after confirming the file's source and name. Fixing permissions won't resolve an architecture mismatch or a missing system library.
Folder permissions: check whether the actual data location is writable
On startup, v2rayN may write settings, logs, a database, and temporary core config files. Being able to read the program files doesn't mean the user data folder is writable. A portable package in a protected folder, launching from inside an archive, or restoring a read-only backup to the working folder can all cause startup errors.
-
Exit the app and make a backup
Exit v2rayN from the system tray and confirm in Task Manager that its process has ended. Copy the original program folder and the actual data folder. Keep the original logs, and don't repeatedly test on your only copy of the data.
-
Extract the entire package
For testing, extract the portable package to
Documents\v2rayN-testin your user folder. Don't launch the main program from an archive preview window or extract only the executable. -
Check write access
In the data folder shown in the logs, create a text file, save it, and delete it. Right-click the folder, choose “Properties” → “Security,” select your user account, and check the “Write” and “Modify” permissions.
-
Check for blocked files
Go to “Windows Security” → “Virus & threat protection” → “Protection history” and check whether the program or core was blocked. Once you've confirmed the file's source, address that specific file. Don't disable your entire security suite.
-
Launch as a standard user
Launch the app as a standard user from the new folder. If the interface opens, go to “Settings” → “Parameter settings” and note the local listening ports. Menu labels can vary by version, so use what's shown in your app.
If the app launches only as an administrator, check access controls on the original program and data folders rather than relying on elevated privileges as a permanent fix. A standard local proxy usually doesn't need elevated permissions to launch. TUN mode requires permissions for a virtual network adapter and routing, so test it separately after the app starts normally.
Corrupt config: isolate user data before restoring it piece by piece
An interrupted update, forced shutdown, or manual config edit can cause JSON parsing errors or database read failures. Interface settings, the subscription database, and the config generated for the core are separate layers of data. If the core reports an invalid field, you don't necessarily need to delete all subscriptions. If the interface can't read the database, changing VLESS parameters won't fix it.
System.Text.Json.JsonException
Cause: JSON parsing failed because of a format or data type issue. Use the path and line number following the exception to locate it. Fix: Back up the file mentioned in the error, then compare it with a config generated by the same version. Don't clear files you haven't identified.
database is locked
Cause: Another process or an unfinished write may be locking the database; it isn't necessarily corrupted. Fix: Close duplicate instances, confirm their processes have exited, and try again. Don't move the database or delete its related files while it's open.
- Create a clean baseline: Fully extract the same version to a new folder without copying over the old settings. If the program still reads the old data folder, the new folder hasn't isolated the problem.
- Find the data path: Use the startup logs, package instructions, and any data-folder option in the interface to locate the user data used by this instance. Don't delete files based on fixed filenames from another version.
- Isolate data reversibly: Exit the app completely, then rename the config or entire data folder mentioned in the error so you can keep it. Let the program create fresh data. If you can't confirm the path, stop and collect a backup and logs first.
- Restore one item at a time: Once the interface works, import one known-good node and test it. Then restore subscriptions, routing rules, and advanced settings. Don't start by copying the entire old folder back.
If the app starts with clean data but exits again after you restore a particular set of settings, you've narrowed down the problem to that data. For VMess and VLESS nodes, check only the transport and security settings actually used by the node; don't treat TLS, transport, and routing fields as interchangeable. After basic connectivity is restored, check complex routing rules against the Complete Configuration Guide.
Port conflict: identify the PID before stopping a process or changing a port
A local listening port conflict usually prevents the proxy core from starting, but may not close the v2rayN interface. If the log says address already in use or reports a bind failure, first check the local listening settings under “Settings” → “Parameter settings.” The examples below use ports 10808 and 10809 for checks; not every version uses both ports.
Run this PowerShell command to list the owners of these TCP listening ports. If your config uses different ports, query those instead. No output means this query found no matching TCP listeners; it doesn't rule out UDP or every other address family.
Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
Where-Object { $_.LocalPort -in 10808,10809,20808 } |
Select-Object LocalAddress,LocalPort,OwningProcess
Get-Process -Name v2rayN -ErrorAction SilentlyContinueAfter you get the number for OwningProcess, find the PID in Task Manager under “Details” and verify the process name and path. If it's an old v2rayN instance, exit it normally from the system tray first. Don't force-quit an unfamiliar PID that may belong to a system service. If another required program is using the port, change the corresponding v2rayN listening port to an available one, then restart the core.
Bottom line: change only the listening port that's in conflict
If you change the listening port to 20808, also update your browser's manual proxy settings, terminal proxy variables, and any other apps that use the old port. If system proxy is enabled, reset it and verify the actual proxy address. The server's remote port is separate from the local listening port; don't change both.
On Linux, use this command to check the corresponding listening port. If the port isn't in use but binding still fails, check the logs for permission errors, a missing listen address, or security policy restrictions. Repeatedly changing ports won't help identify those issues.
ss -ltnp 'sport = :10808'
ss -ltnp 'sport = :10809'
ss -ltnp 'sport = :20808'After the app starts: verify it and troubleshoot common questions
Getting the window back is only the first step. Keep the default or simplest routing, select a known-good node, and check that the core log remains stable. Then enable the system proxy and test browser access. Restore subscription updates, custom DNS, routing rules, and TUN one at a time so you can roll back the change if the problem returns.
Installed .NET, but the app still flashes and closes. What should I check next?
Recheck the framework and architecture specified in the alert, then run dotnet --list-runtimes. If there's no runtime alert, check the exception entries under “Windows Logs” → “Application.” Don't install multiple unrelated major versions one after another.
Why does v2rayN still load the old config from a new folder?
The program may use a separate user data folder. Check the actual path in the logs, exit the app, and back up that folder before testing a reversible isolation. Moving only the program files doesn't guarantee a fresh config.
Will deleting all config files fix it in one go?
You'll lose subscriptions, nodes, and rules, and may hide the real cause. Back up first and isolate the data mentioned in the error. Once you've confirmed the app works with clean data, restore items in batches. Don't wipe your only copy.
The interface works, but the app fails when I enable TUN. What should I do?
Turn off TUN and test the node and core using the local proxy. If the standard proxy works, check TUN permissions, the virtual network adapter, and routing logs. Don't assume this is an interface runtime issue.
If the problem persists, note your operating system version and architecture, the actual v2rayN version, package type, time of the error, most recent change, and the first error message with sensitive details removed. Keep the log lines around the error, but hide subscription links, UUIDs, passwords, and remote addresses. Use these details to continue with the FAQ; they're more useful than simply saying the app won't open.