Clash Verge Crash Troubleshooting

First, distinguish a disappearing window from a stopped kernel

If Clash Verge crashes as soon as you open it, save the logs first, then identify which layer failed. Don’t start by deleting the config directory.The desktop UI, background service, and mihomo kernel are separate processes. The UI may close because of WebView2 or damaged app state files. If the UI stays open but the proxy stops working, check the kernel config, listening ports, and TUN permissions instead. A failed node latency test alone does not prove the client crashed on startup.

This guide covers troubleshooting for both the original Clash Verge and the later Clash Verge Rev, but their directories and menus are not necessarily the same. Note the project name, full version, installer architecture, and OS version you’re using. On Windows, press Win + R, enter winver, and check your OS version. Back up your data before switching clients; don’t copy old-version state files over a new-version directory.

In Windows Task Manager, open the Details tab and check whether the app process has exited, then check the system tray. If only the window is hidden, restore it from the tray. If the background process is stuck, try closing the app normally; if necessary, end only the process you’ve confirmed belongs to this client. Don’t terminate every process whose name includes “proxy” or “service.”

Find the startup logs and crash timestamp

If the UI opens, start with the app’s directory menu

In Clash Verge Rev, look under Settings for “App Directory” or an option to open the directory, then check the log folders. Menu labels may vary between versions. On Windows, installed versions typically store data under the user’s %APPDATA% folder; portable builds may keep it next to the app. Don’t assume your installation has no logs based on a path you found online.

If the app won’t open, use the PowerShell command below to list candidate data folders with “Verge” in the name. This only reads the folder list; it won’t delete or change any files. Once you find a folder, look for the latest log files by modification time. Save app, service, and kernel logs separately if available.

# Windows PowerShell: Find candidate user data folders
Get-ChildItem -LiteralPath $env:APPDATA -Directory -Force |
  Where-Object { $_.Name -match 'verge' } |
  Select-Object Name, FullName, LastWriteTime

If the UI won’t open at all, check system records too

1. Note the local time and reproduce the crash just once to avoid older logs being overwritten by repeated launches.
2. Press Win + R, enter eventvwr.msc, then go to Windows Logs → Application and check for errors from the same minute.
3. Record the faulting application, faulting module, exception code, and path. Event IDs 1000 and 1001 can be useful clues, but not every crash generates them.
4. You can also run perfmon /rel to open Reliability Monitor and view app failure details for the relevant date.

Entries such as fatal, error, and panic in kernel logs are starting points, not a complete diagnosis. Read about 20 lines before and after each entry: a final “process exited” message is often just the result, while the cause may be an earlier config parsing or port binding failure. A GUI app producing no terminal output doesn’t prove it had no error.

Corrupt config: validate it before isolating it

If the logs show yaml: line 18, unmarshal, parse config, or a missing policy name, start by tracing the config chain. YAML is sensitive to indentation and data types. Tabs for indentation, lists written as strings, or references to deleted policy groups can all prevent the kernel from starting. But a UI state file parsing error and a proxy config parsing error are different problems and should be handled separately.

Test with the kernel bundled with your current installation

mihomo provides the -t config test flag, which checks a config without starting normal proxy listeners. This example assumes your terminal is in the directory containing mihomo.exe and that you copied the file being tested to config-test.yaml. The bundled kernel may have a different filename. Use the one included with your current client rather than swapping in another kernel and drawing conclusions from that.

# Windows PowerShell: Test a separate copy of the config
.\mihomo.exe -t -f .\config-test.yaml
$LASTEXITCODE

If the test fails, save the full output and exit code. Configs that use rule sets, geodata, or relative file paths also depend on the working directory and external resources. Handle “resource not found” separately from YAML syntax errors. A passing test only confirms the config passed under those test conditions; it doesn’t verify service permissions, TUN, or network connectivity.

1. Back up everything: Exit the app, make sure its processes have stopped, and copy the user data folder to a separate location. It may contain subscriptions, overrides, scripts, rules, and UI settings.
2. Undo the last change: If the problem started after editing a rule or script, revert that change first. Don’t update subscriptions, replace the kernel, and change ports all at once.
3. Find the config actually in use: The client may merge subscriptions, overrides, and scripts before passing the result to the kernel. A valid source subscription doesn’t guarantee the merged config is valid.
4. Isolate app state: Only rename a UI state file after backing it up and when the logs point to that file. Don’t guess a filename and delete files in bulk.

If you need to test with a fresh data directory, first stop the client and its related services and save the original directory. Then create a separate environment using a method supported by that version. If the app starts in the new environment, that makes the old environment’s config or state worth investigating further; it doesn’t mean you should permanently discard all your subscriptions. Restore data in batches to narrow the problem down to a specific config or override.

Port conflicts: identify the process listening on the port

An address already in use or bind error usually means another process is listening on the same address. Common example ports include 7890, 7897, and 9090 for the controller, but these aren’t fixed across all versions. Check the active config for mixed-port, port, socks-port, and external-controller.

# Windows PowerShell: Adjust the list for the port in the error
$ports = 7890, 7897, 9090
Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
  Where-Object { $_.LocalPort -in $ports } |
  Select-Object LocalAddress, LocalPort, OwningProcess

# Example: Replace 1234 with the actual process ID found in the previous step
Get-Process -Id 1234

The 1234 above is only an example process ID; don’t use it to end a process. First verify the process name, executable path, and whether it belongs to another proxy client you have open. If an old kernel is still running, try exiting through its client first. If you must end a process, act only on the instance you’ve identified.

• Running two clients at once: Assign different proxy listening ports and controller ports to each. Changing only the proxy port may still leave the controller ports in conflict.
• Changed the proxy port: Also check the system proxy settings and any apps with manually configured proxies; they may still be connecting to the old port.
• The error says access is denied: It may not be a regular process conflict. Port reservations or security policies can also cause this error, so don’t treat it as the same issue.

If the port is free but binding still fails, run netsh interface ipv4 show excludedportrange protocol=tcp to check IPv4 TCP excluded port ranges. Check the corresponding settings for IPv6 as well. Don’t delete system-reserved ranges just to start the proxy; first try a port you’ve confirmed is available.

Kernel permissions and TUN: troubleshoot in stages

For permission denied, access is denied, TUN device creation failures, or service connection errors, first determine whether the failure occurs while “starting the kernel” or “creating the virtual adapter.” System proxy settings mainly affect apps that follow them. TUN routes traffic through a virtual network interface and involves services, permissions, and routing, so it takes more steps to troubleshoot.

Establish a baseline without TUN

1. If the UI is responsive, turn off TUN, keep rule mode enabled, and test the same website through the system proxy.
2. If the proxy works without TUN but fails with it enabled, focus on service status, the virtual adapter, and route logs. There’s no need to switch nodes right away.
3. Check the service mode in your current version’s settings. If the service needs installing or repairing, grant permission for that operation only and review the logs afterward.
4. Press Win + R, enter services.msc, and check the relevant service’s status and executable path to make sure it doesn’t still point to an old installation folder.

Running as administrator can help you compare permissions in a controlled test, but it shouldn’t become a permanent workaround. If a user data file is accessible only with elevated permissions, check its owner, folder access permissions, and installation location. Loosening permissions across an entire drive increases risk.

On Windows, check Windows Security → Virus & threat protection → Protection history for blocked kernel files or components. Verify the file source and event details before taking action; disabling all protection is not a troubleshooting step. On macOS, check Console and any alerts under System Settings → Privacy & Security. On Linux, check terminal or service logs based on how the app was launched; Windows service repair steps don’t apply.

Runtime and installer issues: fix the component identified by the error

The Windows UI in the Tauri-based Clash Verge series typically depends on WebView2. A missing or damaged UI runtime may prevent a window from opening, but a window that flashes briefly isn’t enough to identify WebView2 as the cause. Consider the faulting module in system events, installer errors, and client logs together.

On Windows, go to Settings → System → About to check the system type. Choose an x64 or ARM64 package based on your OS and project support. On macOS, check whether your machine has Apple silicon or an Intel processor. A mismatched architecture, mixed components, or old files that weren’t properly replaced is a more likely explanation for these loading errors than a “broken subscription.”

If you need to reinstall, back up user data and note the current version first. Then close the client and related processes and use a complete installer for the same project. Reinstalling usually doesn’t automatically remove user config, so a crash after reinstalling doesn’t rule out a config issue. Don’t mix program files from the original Clash Verge, Clash Verge Rev, and other clients in the same folder.

Verify the fix and prepare an issue report

Getting the app window to appear is only the first step. Restore things in the order below, changing one variable at a time. If an error returns, save the logs from that point and go back to the last working state.

1. Verify the UI: Open Settings, close the app, and launch it again to confirm it wasn’t a one-time successful start.
2. Verify the kernel: Check the logs for recurring config or listening errors and make sure the kernel process isn’t stuck in a restart loop.
3. Verify the local proxy: Confirm the actual listening port, then test access with an app that follows the system proxy.
4. Restore the config: Import a known-good config first, then restore overrides, custom rules, and subscription updates one at a time.
5. Enable TUN last: Check DNS, routing, and connectivity. Don’t assume that working system proxy settings mean TUN will work too.

In short: confirm whether the process actually exited, find the logs by timestamp, then follow the relevant branch for config, ports, permissions, or runtimes. For help checking config fields, see the protocol handbook. If system proxy or subscription issues remain after recovery, see the FAQ. Before switching clients, compare kernel and platform support; not every startup issue calls for migration.