When a Clash client (Clash Verge Rev, Clash Plus, Clash for Windows, or any other front end running on top of the mihomo core) crashes on launch or "opens and immediately disappears," the software itself is rarely the problem. In the vast majority of cases the real culprit lies in the configuration, a port conflict, a permission gap, or a corrupted file. This article ranks the causes from most to least common based on real-world troubleshooting and walks through verification steps you can follow directly, so you can pinpoint and fix the issue without reinstalling the operating system or repeatedly uninstalling and reinstalling the client.
Why Launch Crashes Are Hard to Diagnose at a Glance
A launch crash is different from a runtime crash. The process usually terminates before the UI has even finished rendering, so there's very little visible information — maybe just a window that flashes and closes, or a taskbar icon that appears and vanishes a moment later. The key thing to understand is that the client itself is typically just a graphical front end (GUI); the actual work of handling proxy rules and establishing connections is done by a separate core process (mihomo, or the older Clash core). A crash could happen in the GUI process, or the core process could be launched by the GUI and then exit immediately — these two scenarios require completely different troubleshooting paths. That's why the first step is always "check the logs," not guesswork.
Step One: Locate the Logs Before Reinstalling
Nearly every Clash client leaves local log files behind, and reinstalling will simply erase those clues, making the problem harder to diagnose. Find the log file at the location shown in the table below before deciding on your next move.
| Platform | Log/Config Directory | Notes |
|---|---|---|
| Windows | %APPDATA%\io.github.clash-verge-rev.clash-verge-rev\logs | Files split by date, recording core launch parameters and error output |
| macOS | ~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/logs | Use "Reveal in Finder" to jump there directly |
| Linux (deb install) | ~/.config/clash-verge-rev/logs | You can also check service logs with journalctl |
| Running mihomo from the CLI | Terminal stdout / core.log under the -d directory | Errors are printed directly to the terminal in foreground mode |
Open the most recent log file and look for keywords such as panic, FATAL, error, and bind: address already in use — they usually point straight to the category of the problem.
Common Cause 1: Configuration File Syntax Errors
This accounts for the largest share of launch crashes, especially when the config file has been edited manually or was provided by a subscription with poorly formatted output. Clash configs use YAML, which is extremely sensitive to indentation and the space after a colon. Common mistakes include:
- Using tab characters instead of spaces for indentation (YAML doesn't allow tabs)
- Inconsistent indentation levels among list items in rules or proxy groups
- A string containing a colon that isn't quoted, causing it to be misparsed as a key-value pair
- Rule providers referencing a proxy group name that isn't defined anywhere in the config
Verification is straightforward: when the core fails to parse the config, the log gives an exact line number and field, e.g. yaml: line 42: mapping values are not allowed in this context. Jump to that line and check the indentation carefully. If the client doesn't even generate a log, the config file probably can't be read at all (for example, it isn't saved as UTF-8) — try re-saving it as UTF-8 without BOM in a text editor and retry.
Tip
Keep a backup before editing the config, even if you're only changing one line. That way you can roll back instantly if something breaks, without having to re-download the subscription.
Common Cause 2: Port Already in Use
By default Clash listens on an HTTP proxy port (commonly 7890), a SOCKS5 port, and a control panel port (commonly 9090). If any of these ports is already occupied — including by a previous Clash process that didn't fully exit — the core will fail to bind the port, log an error, and exit, which shows up in the GUI as "opens and then disappears."
Steps to check:
- Search the log for bind: address already in use or listen tcp :7890 style errors
- On Windows, run netstat -ano | findstr 7890 to find the PID holding that port, then end the process via Task Manager
- On macOS/Linux, run lsof -i :7890 to see what's using the port
- If the offending process is a leftover Clash core, manually end the stray mihomo or clash process in Task Manager/Activity Monitor before relaunching the client
- If it's a genuine conflict with another application, change mixed-port, socks-port, or external-controller in the config to a free port number, save, and restart the client to verify
netstat -ano | findstr 7890
lsof -i :9090Common Cause 3: Corrupted or Mismatched Core Files
Clients like Clash Verge Rev and Clash Plus ship the GUI and the core (mihomo) as separate components, with the core installed alongside the client as a standalone executable. If the download was interrupted, security software mistakenly deleted the core executable, or an incompatible core version was swapped in manually, the GUI will exit immediately after launch because it can't find or run the core process.
Check the following:
- Verify the core executable exists in the client's install directory (usually named verge-mihomo or clash-meta) — if the file size is unusually small (tens of KB), the download was likely incomplete
- Check the quarantine/trust log of your security software (especially aggressive antivirus suites) — the core file is frequently flagged as a false positive and quarantined
- Make sure the core's architecture matches your system — for example, Apple Silicon Macs need the arm64 core and can't use an Intel-built binary
The fix is to reinstall by overwriting with a fresh, complete installer, or to grab the matching core file for your platform from the download center and drop it into the install directory. Add the client's install directory to your security software's trust list afterward to prevent it from being deleted again.
Common Cause 4: Insufficient System Permissions
This is most common when TUN mode (virtual network adapter taking over system-wide traffic) is enabled. Creating a virtual network interface requires elevated permissions on every platform:
- On Windows, the client must run as Administrator, otherwise creating the TUN device fails immediately and the process exits
- On macOS, you need to allow the client to load a network extension under "Privacy & Security" in System Settings. The first time TUN mode is enabled, a system-level authorization prompt appears — if you accidentally dismissed it, you'll need to re-authorize it manually in System Settings
- On Linux, running mihomo as a regular user with TUN enabled requires CAP_NET_ADMIN. The usual approach is running it with sudo, or setting the capability directly on the core executable
If crashes only started right after you enabled TUN mode, it's almost certainly a permissions issue. Disable TUN mode first to confirm the client launches normally, then grant the appropriate permissions as described above.
Recommended Step-by-Step Verification Order
When you hit a launch crash, work through the following order rather than changing several things at once — that's the only way to confirm which step is actually at fault:
Check the logs first to determine whether it's a config parsing error, a port bind failure, or the core process crashing outright.
Temporarily switch to a known-working minimal config (just basic ports and a single direct rule) to verify the client itself can launch.
If it launches, the problem is in your original config — check it section by section for syntax or port conflicts as described above. If it still won't launch, the issue is at the installation or system permission level.
Disable enhanced features one at a time — TUN mode, system proxy takeover, and so on — to narrow it down to the minimal condition that reliably reproduces the crash.
Once you've confirmed it's a core file issue, reinstall using a fresh official installer rather than substituting a core file from an untrusted source.
Safe Configuration Rollback Methods
Rather than repeatedly trial-and-erroring a broken config, it's safer to keep previous versions on hand so you can roll back at any time:
- Most clients automatically keep a backup of the previous version before each update on the "Subscriptions" or "Profiles" page — you can select "restore previous version" directly in the UI
- Before editing a config manually, copy it with a date suffix (e.g. config-2026-05-15.yaml) first, and only delete the old backup once you've confirmed the new version works
- If the config comes from a subscription link, keep a manually exported local copy before updating, in case the subscription server returns bad content that overwrites your working setup with no way back
- After rolling back, restart the client and watch the logs to confirm the crash is gone, then reintroduce your changes one at a time to pinpoint exactly which change caused the issue
Note
Don't delete the broken config until you've confirmed the root cause — archive it instead. It's useful for later comparison and as a sample if you need to report the issue to your subscription provider.
If the Problem Still Isn't Resolved
If the client still won't launch after working through the steps above, consider these fallback options:
- Fully uninstall the client — including wiping the config directory — and reinstall from scratch, to rule out corrupted leftover files from the installation process
- Switch to a different client (for example, from a GUI client to running the plain mihomo core from the command line) to confirm whether the issue is specific to a particular GUI front end
- Test under a low-privilege account or a brand-new user profile to rule out interference from system-level environment variables or local policies
- Keep the complete log file on hand so you can share accurate details when describing the issue in a community or support channel
A launch crash can feel overwhelming at first, but working through it in order — check the logs, narrow the scope, verify with a rollback — usually locates the specific point of failure within fifteen minutes or so. Getting into the habit of keeping config backups and periodically checking for leftover processes and port conflicts will reduce how often this kind of issue comes up in the first place.