2026-09-28 Troubleshooting 10-minute read

Clash Crashes on Startup: How to Diagnose and Fix Launch Problems

Fix Clash startup crashes on Windows, macOS, and Android. Check logs, revert config changes, resolve port conflicts, and reinstall the core.

First, determine whether the app, core, or window has closed

A Clash client typically includes a graphical interface, a proxy core, and optionally a background service. A disappearing window does not necessarily mean the core crashed, and nodes timing out does not necessarily mean the client closed unexpectedly. Identify which component stopped before changing the configuration; otherwise, repeated reinstalls may leave the root cause untouched.

What you see	Check first	How to tell
Window disappears, but the tray icon remains	Setting to minimize to the tray when closing the window	Reopen the window from the tray menu to see if it was simply hidden
Interface works, but reports that the core is disconnected	Config parsing, core process, and controller port	Check the core logs before clearing interface data
Window and process both exit	System crash reports, runtime environment, and app data	Note the time of the exit and the faulting module
App exits only after enabling TUN	Service permissions, virtual network adapters, and other VPNs	Check whether the app starts reliably with TUN disabled

On Windows, press Ctrl + Shift + Esc to open Task Manager, then check the client and core processes under “Details.” On macOS, open Activity Monitor and search for the client name and mihomo. On Android, go to Settings → Apps → the client and distinguish an app exit from a disconnected VPN. Menu names may vary by device manufacturer and Android version.

Back up your configuration, then capture the first error

Keep your subscription and local changes

Fully quit the client and its background service before backing up the configuration directory. Keep your subscription URL, local YAML files, override snippets, rule sets, and policy group selections. The directory depends on the client, so don’t assume one product’s path applies to every Clash client. If the interface opens, use its “Open config folder” or “Open log folder” option where available.

If the interface won’t open, check the installation guide and the OS’s app data locations. On Windows, app data is commonly stored in an application subfolder under %APPDATA% or %LOCALAPPDATA%. On macOS, it’s usually under ~/Library/Application Support/. Don’t delete either parent directory. Android’s private app data is usually inaccessible through a standard file manager; before clearing storage, make sure your subscription and local configuration are backed up elsewhere.

Use timestamps to find the relevant log entries; don’t just check the last line

Windows: Press Win + R, type eventvwr.msc, and open Windows Logs → Application. Look near the time of the crash for Application Error, .NET Runtime, or Windows Error Reporting entries. Note the faulting application, module, and exception code.
macOS: Open Console and review the crash report. You can also check ~/Library/Logs/DiagnosticReports/. Keep the exception type, termination reason, and crashed thread details.
Android: If you’re familiar with ADB, enable USB debugging and use the following commands to capture a startup attempt. Clearing the buffer removes existing logs, so do this only if you don’t need to keep them.

adb logcat -c
adb logcat -v time > clash-startup.txt
# Start the client on your phone now; after reproducing the crash, press Ctrl+C to stop logging

In Android logs, search for FATAL EXCEPTION, AndroidRuntime, Fatal signal, and the app’s package name. On desktop, look for permission denied, address already in use, panic, and config parsing errors. A final “connection failed” message may only be a knock-on effect of the core exiting; the root cause is often earlier in the log.

Use a minimal config to check YAML and core compatibility

If the issue started after updating a subscription, changing an override, or upgrading the core, first revert the most recent change. The subscription source, client overrides, and final runtime configuration are different files. Check what the core actually loads, not just what appears in the subscription editor.

Start with syntax and loading tests

These commands are for mihomo and assume the core and config are in the same test directory. Use a core file that actually exists. For other Clash forks, check the -h help first; don’t assume all command-line options are identical.

# Windows PowerShell
.\mihomo.exe -v
.\mihomo.exe -t -f .\config.yaml

# macOS / Linux
./mihomo -v
./mihomo -t -f ./config.yaml

-t checks whether the configuration passes the loading test. It does not confirm that nodes can connect and is not a substitute for a real startup. If the error points to a YAML line, check for tabs used in indentation, missing spaces after colons, and references to nonexistent policy group names. A parser may stop on the line after the actual mistake, so review the surrounding lines too.

Test subscriptions, rule sets, and TUN separately

After making a backup, create the following minimal config in a separate test directory. It only checks whether the core can start; all traffic is sent directly, with no proxy nodes. Quit the original client during the test to avoid running two cores at once.

mixed-port: 17890
allow-lan: false
mode: rule
log-level: info
tun:
  enable: false
dns:
  enable: false
rules:
  - MATCH,DIRECT

Run .\mihomo.exe -f .\minimal.yaml or ./mihomo -f ./minimal.yaml in the foreground, confirm it keeps running, then press Ctrl + C to stop it. Port 17890 is used to distinguish it from the commonly used 7890; there’s no guarantee it’s available. Don’t enable the system proxy or TUN during the test.

If the core still exits with the minimal config, check its architecture, file permissions, working directory, and system crash reports first.
If the minimal config works, restore nodes, policy groups, rule sets, and DNS one at a time, then restore TUN.
If the issue returns after restoring a particular snippet, keep that snippet and the exact error message, then check the required core features and config format.

Clash, Clash Meta, and mihomo don’t support exactly the same configuration options. A field that’s ignored or rejected can change how the client behaves; valid YAML alone doesn’t mean the config works with your core. For proxy-providers and rule-providers, also check file paths, remote response contents, and read/write permissions.

Check proxy and controller ports, and look for leftover processes

address already in use means the address is already being used by another process. The proxy listening port and controller port serve different purposes. For example, mixed-port: 7890 handles HTTP/SOCKS proxy traffic, while external-controller: 127.0.0.1:9090 is for the management API. These are common values, not requirements; check your active configuration.

Find what’s using a port on Windows

netstat -ano | findstr ":7890"
netstat -ano | findstr ":9090"
# Example: identify the process name for PID 1234
tasklist /FI "PID eq 1234"

Check for the local address and LISTENING status, then identify the process by PID. Don’t mistake the same port in a remote address for a local conflict. If a core process was left over from the previous session, quit it normally from the client or its service. If another program owns the port, decide which service should keep listening rather than force-quitting an unfamiliar system process.

Find listening ports on macOS

lsof -nP -iTCP:7890 -sTCP:LISTEN
lsof -nP -iTCP:9090 -sTCP:LISTEN

If you change the proxy port from 7890 to 17890, update browser extensions, command-line environment variables, and system proxy settings too. Before changing the client’s controller port, check whether the interface will follow the change automatically. A mismatch can show as “core disconnected” even while the core is running.

Fix the runtime environment on Windows, macOS, and Android

Windows: identify the faulting module before changing runtimes

If the logs point to the interface runtime, install the dependency specified in the client’s release notes. For example, a client built on WebView2 needs a working WebView2 Runtime, but not every Clash client uses it. Install the relevant Visual C++ runtime only if a DLL is missing or the release notes explicitly require it. Never download individual DLLs from an unfamiliar site and copy them into a system folder.

Check Windows Security → Virus & threat protection → Protection history to see if the core was quarantined. Verify the installer’s source and the alert before taking action; don’t leave security protection disabled as a workaround. Interface startup and config parsing usually don’t require administrator access. Elevate only for steps that clearly need it, such as installing a service or enabling TUN.

macOS: distinguish Intel, Apple Silicon, and security prompts

Check About This Mac for your processor: choose an arm64 build for Apple silicon and an x64 build for Intel. The “can’t be opened” security warning is different from a crash after launch. For an app from a trusted source, follow the prompt under System Settings → Privacy & Security. Don’t remove security attributes from every app in bulk.

If the report mentions dyld, a missing dynamic library, or an architecture mismatch, reinstall the full app package for your system rather than copying a core from another Mac. For TUN-related issues, disconnect other VPNs first, then check the helper service permissions in the client’s documentation.

Android: troubleshoot startup crashes separately from background disconnects

Run adb shell getprop ro.product.cpu.abilist to see which ABIs the device supports. Choose an arm64, armv7, or universal package based on the device and client support. The APK’s ABI, its minimum Android version, and the version installed on the device must all be compatible.

Go to Settings → Apps → the client → Storage & cache and try clearing the cache first. Clear storage only after making a backup, since it deletes local configuration. If the VPN disconnects after the screen has been locked for a few minutes, check battery optimization and background activity permissions. That’s different from a crash message appearing as soon as you tap the app icon. Android usually allows only one active VPN service per user, so disconnect other VPN apps while testing.

When to reinstall the core or roll back a version

Reinstall or roll back only if the core still won’t start with a minimal config, its file is missing, or an upgrade caused a repeatable crash. Replacing the core at random can break compatibility between the client and controller interface. Don’t rename an arbitrary mihomo executable and drop it into the installation folder.

Preserve the evidence: Save logs and a config backup, note the current client and core versions, and keep the only known-good installer intact.
Stop related processes: Quit the tray app, stop helper services as described in the client’s documentation, and confirm the listening port is free.
Restore matching components: Use the client’s built-in core recovery option when possible. If the interface won’t start, reinstall the complete package for the same version.
Isolate old data: Back up and rename the app’s own data directory so the client creates a fresh one. Don’t delete the system’s entire app data directory.
Test a clean setup first: Don’t import old overrides or enable auto-start or TUN. Confirm that both the interface and core remain running.
Restore items one at a time: Import a known-good config first, then restore DNS, rule sets, and TUN. Change one thing at a time and record the result.

A version regression is more likely if the issue still reproduces in a fresh data directory on the new version, while the previous version works on the same device. For a rollback, use an installer from a trusted source that matches your system architecture. Check whether the newer version’s data format is compatible with the older release; if needed, test each version with a separate data directory.

Post-fix checks and what to include in a bug report

Don’t stop at “the window opens.” Verify each step in order: the interface stays open, the core initializes, the proxy port starts listening, the config imports successfully, rule mode works, and finally TUN. Check the logs for repeated starts or exits at each stage before moving on.

Quit normally and restart once to confirm the correct config still loads.
Restart the system and verify service permissions and proxy settings; make sure it works without relying on a manual launch.
Include the client, core, and OS versions, the system architecture, and details of the most recent upgrade or config change.
Attach redacted logs, the time of the crash, and the shortest steps to reproduce it. Note whether the minimal config triggers the same exit.

Follow the same order: identify which component exits, then check the logs; revert config changes, then check ports; verify the runtime environment before reinstalling matching components. This helps preserve your existing rules and narrow down “Clash crashes on startup” to a specific, reproducible cause.