Use this guide if double-clicking v2rayN does nothing, it closes immediately after launch, or your Mac says the app is damaged or can’t be verified. First determine whether the UI failed to launch, the core failed to start, or the proxy connection failed. Then check Windows runtimes, macOS security alerts, or Linux dependencies. Back up configuration files before changing them, and only adjust system permissions for an app whose source you’ve verified.
First, identify the failure: UI crash or core not starting
v2rayN is a desktop client: its UI manages subscriptions, nodes, and settings, while the selected core handles proxy connections. A window that opens but reports a core exit in the logs is a different problem from an app that never opens. Check VLESS or VMess settings and subscription URLs after restoring the UI; don’t start by deleting all your nodes.
| What you see | What to check first | What you can leave alone for now |
|---|---|---|
| Nothing happens after double-clicking | Stale processes, package architecture, runtimes, and system security alerts | Subscriptions and Routing |
| The window appears, then closes immediately | Crash reports, configuration loading, and write access to the data directory | The node’s transport protocol |
| The window opens, but the core won’t start | Core logs, execute permissions, and local port conflicts | The UI runtime |
| The core runs, but websites won’t load | System proxy, routing, DNS, and node reachability | Reinstalling the desktop app |
Look for v2rayN in Windows Task Manager or macOS Activity Monitor. If the process is still running, check the system tray or menu bar to see whether the window is hidden. If you need to end the process, close only the client process you’ve identified, then launch it once more and note the exact error and when it occurred.
Windows: Check the .NET Desktop Runtime and package architecture
If Windows reports a missing runtime, don’t assume that having “.NET installed” means all dependencies are covered. .NET Runtime, ASP.NET Core Runtime, and .NET Desktop Runtime provide different components. Builds that depend on the Windows Desktop framework need the corresponding desktop runtime; other UI builds or self-contained packages may have different requirements. Follow the package notes and the startup message for your specific build.
Error: You must install or update .NET to run this application.
Cause: The launcher couldn’t find a framework that meets the required version and architecture.
Fix: Note the Framework, Version, and Architecture shown in the message, then install the matching component. Installing just any version of the SDK may not help.
Error: This app can't run on your PC
Cause: The app’s architecture, system compatibility, or extraction may not match what’s required.
Fix: Check your system type and the package architecture, extract the entire package to a local folder, then try launching the main app.
-
Check your system type
Go to Settings → System → About and check System type. x64 and ARM64 are different architectures; don’t choose a package based only on the processor brand.
-
Check the framework requirements
If the app folder contains
v2rayN.runtimeconfig.json, open it in a text editor and look forframeworkorframeworks. For example, if the version forMicrosoft.WindowsDesktop.Appis8.0.0, check for the corresponding .NET 8 Desktop Runtime. This is an example for identifying the requirement, not a claim that every version needs .NET 8. -
List installed frameworks
Run the command below in a terminal and compare the framework names and major versions. If
dotnetisn’t found, the shared runtime may not be installed or PATH may be misconfigured. Self-contained packages may not depend on the system runtime. -
Check the crash details
Press Win+R, enter
eventvwr.msc, then open Windows Logs → Application. Find a .NET Runtime or Application Error event from the same time and note the exception type and faulting module.
dotnet --list-runtimes
dotnet --infoDon’t drag just one executable out of the archive. Missing configuration, dependencies, or resource folders can prevent startup. First test the complete app from a local folder writable by your user; a normal write-permission issue doesn’t necessarily mean you need to run it as an administrator. If system protection reports a quarantined file, verify its source and review the detection details rather than disabling protection altogether.
macOS: Tell quarantine alerts, signature issues, and execute permissions apart
On a Mac, “developer cannot be verified,” “app is damaged,” and “permission denied” are different problems and shouldn’t all be handled with the same command. First check your chip in Apple menu → About This Mac, then choose the matching macOS package. Copy the app from the disk image to Applications before opening it. Don’t run it from a read-only image or keep updating it inside the image.
Error: Developer cannot be verified
Cause: macOS hasn’t allowed the downloaded app to run. The exact message varies by macOS version.
Fix: After verifying the download source, try opening the app once. Then go to System Settings → Privacy & Security. If the app appears with an Open Anyway option, follow the prompts to confirm.
Error: The app is damaged and can’t be opened
Cause: The download or extraction may have failed, signature verification may have failed, or the app may have been modified. Don’t assume this is just a quarantine flag.
Fix: Download a fresh package for the correct architecture and replace the app, then check the security assessment. If signature verification fails, don’t try to hide the problem by removing the quarantine attribute.
Error: Permission denied
Cause: The program being called may not have execute permission, or its directory may not be accessible.
Fix: Use the logs to identify the specific file. Prefer reinstalling the complete app, and check permissions only for the verified target. Don’t recursively loosen permissions across the whole directory.
The commands below assume the app is installed at /Applications/v2rayN.app. If Finder shows a different app name, confirm its actual path first. The first two commands read the architecture and extended attributes; the last two check the signature and macOS security assessment. None of them modify the app.
uname -m
xattr -l "/Applications/v2rayN.app"
codesign --verify --deep --strict --verbose=2 "/Applications/v2rayN.app"
spctl --assess --type execute --verbose=4 "/Applications/v2rayN.app"arm64 is the native architecture for Apple silicon; x86_64 is for Intel. Use the full security assessment output to understand why an app was rejected. Lack of notarization and modified app files are not the same issue. If you can’t verify the app’s source, or signature checks clearly report damaged resources, stop and download the app again.
xattr -dr com.apple.quarantine "/Applications/v2rayN.app"If a command reports insufficient permissions, don’t immediately rerun it with elevated privileges. First check whether another account installed the app; if necessary, have an account with the required access copy and install it again. To find crash details, open Console → Crash Reports and search by app name and time. Before sharing a report, remove usernames, personal folder paths, and any server details.
Linux: Launch from a terminal and install the missing dependencies
If double-clicking the Linux desktop icon does nothing, terminal output is often more useful than reinstalling. Run uname -m to check the architecture, then verify your distribution and package format: Debian-based systems generally use DEB packages, while RPM-based distributions need the matching RPM package. The right package format doesn’t guarantee your system version meets all runtime requirements.
- Installing a package: Use your distribution’s software installer or package manager, and keep any dependency error output. On Debian-based systems,
sudo apt --fix-broken installcan attempt to repair dependencies for installed packages. Review the proposed changes, including any packages to install or remove, before confirming. - Running an extracted package: Check the actual name of the main executable in your file manager, then open a terminal in that directory and run it. Don’t guess the filenames inside the package or copy only the main executable and leave out its neighboring dependencies.
- Desktop session: Launch the app from a terminal under your current desktop user. If you run it over a remote, headless session, a display server connection error doesn’t mean the app files are damaged. Don’t run a desktop app as root to work around it.
Error: error while loading shared libraries
Cause: The dynamic linker can’t find a shared library named in the output, or can’t find one for the matching architecture.
Fix: Search for a package provided by your current distribution using the full library name. Don’t copy a library with the same name from another system and overwrite local files.
Error: Exec format error
Cause: The executable format may not match your system architecture, or the file may be incomplete.
Fix: Compare uname -m with the package architecture and download the right file. Adding execute permission won’t fix an architecture mismatch.
uname -m
cat /etc/os-release
dotnet --list-runtimes
journalctl --user -b -n 80 --no-pagerThe last command checks only the last 80 entries in the current user’s logs for this startup attempt; whether it shows a client error depends on how the app was launched. Keep any output printed directly to the terminal as well. If you see a version requirement such as GLIBC_2.xx not found, don’t manually replace the system’s core C library. Choose a compatible build or upgrade the system using your distribution’s recommended process.
The window opens, but you can’t connect: check ports, the core, and TUN
At this point, the desktop app itself is running. Focus on the core logs rather than installing .NET again. An Xray configuration error, incomplete node settings, or a busy local listening port can all leave the window open while connections fail. Android clients v2rayNG and v2flyNG use the Xray and v2fly cores, respectively, and have different installation methods and startup dependencies. Desktop runtime fixes don’t apply to them.
If the logs specifically show that binding to TCP port 10808 failed, run the first command below on Windows or the second on macOS and Linux with the required tool installed. This is only an example port; not all versions listen on it by default. Use the number shown in your logs.
netstat -ano | findstr ":10808"
lsof -nP -iTCP:10808 -sTCP:LISTEN- If you see
address already in useorOnly one usage of each socket address, identify the process using the port first. If it’s a duplicate client instance, close the extra one. Don’t terminate an unknown system process. - After changing the listening port, also check any proxy address entered manually in your apps. The system proxy and an app’s own proxy settings are separate, so a leftover port can leave one app offline even when the core is running normally.
- If the problem starts only after enabling TUN, turn TUN off and test in regular proxy mode. TUN requires additional network interfaces and permissions; granting write access to the entire client directory won’t fix it.
- If the logs say a core file can’t be executed, check whether it’s quarantined, complete, and built for the right architecture. Don’t mix and match core files from different versions to overwrite an existing installation.
Summary: Choose what to fix based on when the failure occurs
If there’s no window, check the runtime environment. If the window opens but the core exits, check the core logs. Only check the system proxy and routing after the core is running. Change one thing at a time and test again; changing the subscription, port, and permissions together makes it hard to identify the cause.
Isolate the configuration last, and keep a recoverable backup
If the same package starts with a clean configuration but exits when it loads the old one, then investigate configuration compatibility or corrupted local data. Reinstalling usually doesn’t remove user data, so a crash after reinstall doesn’t prove the app files are fine—or mean you need to delete the entire user folder.
-
Quit and back up
Quit the client completely. Use the package documentation and error logs to identify its data directory, then copy the entire directory to a backup location. Paths vary by platform and installation method, so don’t delete files based on a generic path.
-
Separate the app from its data
Put the new app in a separate location. Extracting it separately isolates the data only if the package explicitly stores data inside the app directory. If it still uses the same user data directory, back it up first, then rename the confirmed data directory to keep it intact.
-
Restore settings one at a time
First verify that an empty configuration opens and the app exits normally. Then restore one subscription group, followed by routing and other settings. Don’t copy the entire old directory back, or you may reintroduce whatever triggered the crash.
-
Prepare a useful bug report
Record the OS version, CPU architecture, package type, time of the error, and the complete error text. Before sharing logs, redact subscription URLs, node credentials, UUIDs, private domains, and personal paths. Keep the exception name and stack location.
If the app still crashes with a clean configuration, record the simplest steps to reproduce it: install the app, don’t import a subscription, and leave TUN disabled. Then note the exit details. Continue narrowing it down with the FAQ. Once the app starts reliably, follow the setup guide to restore subscriptions, the system proxy, and Routing. There’s no need to restore every advanced setting at once.