Clash Client Won't Open or Crashes Instantly? Log-Based Fix for Startup Crashes

Why the client crashes right at launch

Clash-family clients (Clash Verge, Clash Meta clients, and various GUI shells built on the mihomo core) are structurally two layers: an upper client process that handles the interface, system tray, and subscription management, and a lower core process that actually handles traffic forwarding (typically mihomo or its predecessor, Clash Premium). A startup crash can happen at either layer, and the causes differ completely — a client interface crash is usually a corrupted install, missing dependencies, or a system permission issue, while a core process crash can almost always be traced back to one of three things: the config file, port conflicts, or a leftover process.

Before jumping to a reinstall, figure out exactly which symptom you're facing: "the window never appears," "the window opens but closes the moment you connect," or "it launches on boot and vanishes instantly." These three symptoms call for entirely different troubleshooting paths, and blindly uninstalling and reinstalling rarely fixes the root cause — it'll just come back after the next update.

Step 1: Check the logs, don't guess

Almost every crash scenario leaves its first clue in the logs, so skipping straight to searching "why does it crash" just wastes time. Logs typically live in two places: the client's own runtime log, and the core's connection log.

Windows: Client logs usually sit under AppData\Roaming or AppData\Local in a folder named after the product, with a subfolder typically containing logs; core logs live in a logs subfolder inside the config directory, named by date.
macOS: Client logs usually land under ~/Library/Logs/ in a folder named after the product; you can also open the Console app and filter by process name to see the exception stack the system threw at crash time.

Open the most recent log and look for three keyword patterns:

yaml: line or unmarshal — a config file syntax or field-type error;
bind: address already in use — a port conflict;
panic or fatal error — a core runtime crash, usually with a call stack attached.

Copy the exact error text — the next three steps basically just map to whichever error type you found, so you don't need to read through the whole log.

time="2026-05-20T21:14:02+08:00" level=fatal msg="Parse config error: yaml: line 47: mapping values are not allowed in this context"

An error like this points straight to line 47 of the config file — usually a misplaced indent or an extra colon after a colon. It's not a client bug.

Step 2: Clear the cache and any leftover core process

If the logs show no obvious config error but the client still dies halfway through opening, it's most likely a corrupted local cache file or a zombie core process from a previous unclean shutdown still hogging resources. To fix it:

Search Task Manager (Windows) or Activity Monitor (macOS) for the core process name (commonly mihomo, clash-meta, or clash). If an instance is already running, end it manually before launching the client again.
Close the client and delete the cache file in the config directory (usually named cache.db or similar — don't delete your subscription yaml files). A corrupted cache file like this is a common cause of crashes right after an update.
If the client offers a "reset panel cache" or "restore defaults" option, use it instead of deleting files by hand — it's safer and won't accidentally wipe your subscription info.
Relaunch the client and see if it behaves normally.

Note Export or back up your subscription links and custom rules before cleaning up. Resetting the panel cache usually leaves subscriptions untouched, but manually deleting the wrong folder can wipe your config too.

Step 3: Check whether a port is already in use

Clash-family clients need to bind several local ports at startup: the HTTP/Mixed proxy port (default is often 7890), the control panel port (default is often 9090), and, with TUN mode enabled, ports tied to the virtual network adapter. If any of these are already taken by another program, the core process fails to start outright — showing up as the client window flashing and closing, or getting stuck on "connecting."

How to check:

Windows: Open Command Prompt and run netstat -ano | findstr 7890 (swap in whichever port your config actually uses). Any output means the port's taken — note the PID in the last column and check Task Manager to decide whether to close it.
macOS: Open Terminal and run lsof -i :7890 to see the process name and PID holding that port.

Common causes of port conflicts: having two Clash-family clients installed at once (an old version not fully removed, for example), another proxy tool running on the system, or a zombie process from a previous core instance that never exited cleanly and is still holding the port. Once you know the source, close the extra process, or simply change port and external-controller in the config to different open ports and restart.

mixed-port: 7891
external-controller: 127.0.0.1:9091

Step 4: Validate the config file syntax

YAML is extremely picky about indentation and the space after a colon, and it's easy to introduce a syntax error when hand-editing a config or stitching rules together from different sources. Beyond the line number in the log, here are a few ways to self-check in advance:

Make sure every colon on a line is followed by a space — YAML requires a space between key: and value; writing key:value gets parsed as a plain string and fails.
Make sure indentation is consistently spaces, never mixed with tabs, and that the same nesting level always uses exactly the same number of spaces.
Make sure every proxy name referenced under proxy-groups actually exists in the proxies list — a mismatched name means the reference can't be resolved, and some clients will crash outright instead of showing an error.
If the config was auto-generated from a subscription link, try running it through the client's built-in "validate config" or "syntax check" feature first — most GUI clients expose this in settings.

If it turns out the issue lies in a config pushed by your subscription provider, temporarily switch to an older config you know works, confirm the client itself is fine, and then follow up with the provider.

Windows vs. macOS: common crash scenarios compared

Symptom	Common cause on Windows	Common cause on macOS
Clicking the icon does nothing, no window ever appears	Install files quarantined or deleted by security software — reinstall and add to the trusted list	App hasn't been granted Accessibility or Network Extension permission — allow it manually in System Settings
Window opens, then closes itself within seconds	Corrupted cache file, or a conflict with leftover files from an old version	Gatekeeper blocking an unsigned component — allow it under Privacy & Security on first run
Crashes after clicking "connect" or loading a subscription	Config syntax error or port conflict	Config syntax error or port conflict (OS-independent, same on both platforms)
Crashes after enabling TUN mode	Virtual adapter driver not installed correctly — reinstall once with administrator rights	System extension not approved — allow it manually under Privacy & Security, then restart
Launches at startup but is nowhere to be found	Startup item runs before networking is ready, so the core fails to bind its port	Incomplete login item permissions — try removing the old login item and re-adding it

Still stuck? Work through this checklist last

If you've gone through all four steps and the problem persists, work through this list in order — it covers nearly every remaining edge case:

Confirm the installer matches your system architecture — installing an x64 build on an ARM Windows device, or a build that only supports Apple Silicon on an Intel Mac, will cause launch failures.
Fully uninstall, manually delete the leftover config directory (back up your subscription links first), then reinstall the latest version to avoid field-compatibility issues left over from a cross-version upgrade.
Temporarily disable your security software or firewall as a test. If it launches fine with them off, real-time protection is blocking the core process — add the client to the allowlist.
If the installer came from a third-party source, switch to the official download channel and grab a fresh copy — a tampered or corrupted installer can cause exactly this kind of runtime failure.

Summary Over 90% of startup crashes point to a clear direction right at the "check logs" step: fix the syntax at the line number for config errors, switch ports or kill the process for port conflicts, and reset the cache for corruption. Reinstalling should be a last resort, reserved for the rare remaining edge cases.