Clash Client Crashing on Startup? Windows & macOS Troubleshooting Guide

Figure Out Which Layer Is Crashing

Startup failures fall into two distinct layers, and the fix depends entirely on which one you're dealing with. Spend a minute identifying the layer before touching anything.

• GUI-layer crash: double-clicking the icon does nothing, the process appears then instantly quits, or the window shows a blank white screen. Usually caused by a missing runtime dependency, an installer built for the wrong system architecture, or insufficient permissions.
• Core-layer crash: the app opens fine, but you get "core launch failed," "Clash core exited," or the system proxy toggle throws an error the moment you flip it. Usually caused by a corrupted config file, a port conflict, or a leftover core process from a previous session.

To tell which one you're facing: open the client's log page, or check the logs folder in its data directory directly. If logging stops during app initialization, it's a GUI-layer issue; if you see error lines from the mihomo or clash core, it's a core-layer issue. For core-layer problems, check your config file first; for GUI-layer problems, check your runtime environment first.

General Checks: Config Files & Subscriptions

A corrupted config file is the number one cause of core-layer crashes. Clash configs are written in YAML, which is picky about indentation and special characters — a single formatting error can make the core exit right at the parsing stage on startup.

There are three common ways a config file gets corrupted:

• A tab character slipped in while editing the config by hand. YAML only allows space indentation, and a single tab is enough to break parsing entirely.
• The subscription URL returned something that isn't YAML — an error page, a login page, or empty content — and the client wrote it to disk as-is, with no way to parse it.
• The client was writing to the config file when it crashed or was force-quit, leaving a truncated, half-written YAML document behind.

The right move is to let the client rebuild its config from scratch, not to hand-edit line by line:

1. Quit the client completely, then locate its config directory (see the table below).
2. Rename the entire directory to back it up — for example, append a .bak suffix to the folder name.
3. Restart the client. It will automatically regenerate a default config.
4. Re-import your subscription, confirm the client starts up fine, then selectively copy back any custom rules from your backup.

Another frequent source of corruption is the cache.db cache file, which stores runtime state like Fake-IP mappings. A sudden power loss or crash can corrupt it and cause the core to fail immediately on startup. Just delete the file — the client will regenerate it, and your config is unaffected.

Windows Troubleshooting Steps

Repair the WebView2 Runtime

Tauri-based clients like Clash Verge Rev and Clash Nyanpasu rely on the system's WebView2 component to render their UI. If WebView2 is missing or broken, the typical symptoms are a blank white window or the app quitting immediately after launch.

Open Settings → Apps → Installed apps and search for WebView2. If it's listed, choose Modify → Repair; if it's missing entirely, download and install the Microsoft Edge WebView2 Runtime from Microsoft's site, then restart the client. Electron-based clients (like Clash for Windows) ship with their own rendering engine and don't depend on WebView2 — you can skip this step for those.

Check for a Port Conflict

If the default mixed port 7890 is already in use by another program, the core will fail to start. Run this in Command Prompt:

netstat -ano | findstr :7890

Any output means the port is occupied — the last column is the PID of the process holding it, which you can look up under "Details" in Task Manager. It's often a leftover Clash core process from a previous session that didn't shut down cleanly; just end it. If you'd rather not touch the other process, you can change the mixed port to something free, like 7897, in the client's settings instead.

Clear Out Leftover Processes

If the client crashed or was force-quit, its core process may still be running in the background, causing port and file-lock conflicts on the next launch. Run this from an elevated (admin) Command Prompt:

taskkill /F /IM verge-mihomo.exe
taskkill /F /IM clash-meta.exe
taskkill /F /IM mihomo.exe

Use the actual core process name for your client. A "process not found" message just means there was nothing left to clean up.

Permissions & Security Software

• TUN mode and service mode both require administrator privileges. Right-click the client icon and choose "Run as administrator" to check whether the crash is permissions-related.
• Some security software blocks the core from accessing the network, or mistakenly quarantines its executable. Check your antivirus's quarantine list, restore any quarantined files, and add the client's install folder to the trusted/allowed list.
• Avoid special characters in the install path beyond standard letters and spaces — some older client versions don't handle non-ASCII paths reliably.

macOS Troubleshooting Steps

"App Is Damaged and Can't Be Opened" & the Quarantine Flag

Apps downloaded from a browser that haven't been notarized get flagged by Gatekeeper with a quarantine attribute, which shows up as "app is damaged" and quits immediately when you double-click it. The file itself is usually fine — you just need to clear the quarantine flag. Open Applications → Utilities → Terminal and run:

sudo xattr -rd com.apple.quarantine /Applications/Clash\ Verge.app

Swap in the actual app name for the path, enter your login password when prompted, then launch it normally.

Confirm the Chip Architecture

Apple silicon (M-series chips) needs the arm64 build; Intel Macs need x64. Installing the wrong one typically shows up as the Dock icon bouncing once then quitting, and running the binary manually in Terminal throws Bad CPU type in executable. Click the Apple menu → About This Mac to confirm your chip, then grab the matching build from the download page and reinstall.

Ports & Leftover Processes

Same idea as on Windows — check the default port first:

lsof -i :7890

If there's output, kill the process using the PID in the second column:

kill -9 <PID>

Or clean up leftover core processes directly by name: pkill -f mihomo.

Fixing Permissions

On first launch, macOS shows an authorization prompt to allow writing system proxy settings — clicking "Cancel" here will break the rest of the startup process. Also, if you've ever run the client with sudo, its config directory may now be owned by root, causing read/write failures when launched normally afterward. To fix ownership:

sudo chown -R $(whoami) ~/Library/Application\ Support/io.github.clash-verge-rev.clash-verge-rev

Swap in the actual directory for your client from the table above.

Clean Reinstall

If targeted fixes haven't worked, do a clean reinstall in the order below. This resolves issues caused by corrupted local data — it won't help if the subscription link itself is dead or the proxy provider is down, since no amount of reinstalling fixes a server-side problem.

1. Quit the client and confirm, using the method above, that all core processes have actually stopped.
2. Rename the data directory to back it up, appending a .bak suffix.
3. Delete the original data directory and uninstall the old version.
4. Install the latest version of the client, then re-import your subscription after launch.
5. Leave TUN mode off at first, and confirm you can connect normally in system proxy mode.
6. Restore your custom settings one at a time, restarting after each change, to pinpoint exactly which setting triggers the crash.

Still Crashing? Collect Logs Before Digging Further

If none of the above works, set the client's log level to debug, reproduce the crash once, then gather the following:

• Your OS version, e.g., Windows 11 23H2 or macOS 15.5.
• The client name and version number, plus the core type (mihomo or Clash Premium).
• A complete set of reproduction steps — everything from double-clicking the icon to the crash itself.
• The error lines from the log right around the crash — the last thirty lines are usually enough.

Search the client's GitHub Issues page with this information in hand — most startup crashes already have a known cause and fix version documented. If nothing matches, file a new issue with the details above; it'll get you a useful response much faster.