Clash Crashes on Startup? Check Logs, Fix YAML Errors, and Roll Back Config

1. Tell a closed window, stopped core, and connection failure apart

If the window disappears after Clash starts, that doesn't necessarily mean the same thing every time. Desktop clients typically include a graphical interface, a proxy core, and optional service or TUN components. The interface may close while the core keeps running in the background; if the core fails to start, the settings window may still remain open. First identify which component stopped, then decide whether to change the configuration or repair the installation files.

What you see	Check first	Next step
Window closes, but the tray icon remains	Check whether closing the window minimizes it to the tray	Reopen it from the tray and confirm the process is still running
Window and main process both disappear	Application logs and system crash reports	Note the error time and faulting module
Interface works, but the core keeps restarting	Config parsing, listening ports, and core files	Read the first error before the core exits
Process is running, but websites won't load	System proxy, DNS, and selected proxy group	Troubleshoot the connection; don't reinstall right away

On Windows, press Ctrl + Shift + Esc to open Task Manager, then check the client and core processes under Details. On macOS, look for the corresponding processes in Activity Monitor. Process names vary by client packaging, so don't rely only on whether clash.exe appears.

2. Find the log directory and capture the errors before exit

If the interface still opens

Start with the client's Logs page and look in Settings for an entry named something like Config Directory, Data Directory, or Log Directory. Menus vary by client, and the installation directory is not necessarily the data directory. Sort the files by modification time and open those that match the failed startup. Keep both interface and core logs.

You can temporarily change the log level from info to debug, reproduce the issue once, then switch it back. Debug logs may include domains, node names, and local paths; redact these before sharing. Raising the core log level won't produce an interface crash report if the core never starts.

If the window won't open at all

Windows data directories: Press Win + R, open %APPDATA% and %LOCALAPPDATA% separately, then search for a folder named after the client or its application ID. Check the most recently modified logs. For portable versions, also check the data folder next to the program.
Windows system logs: Press Win + R, enter eventvwr.msc, then go to Windows Logs → Application and look for an Application Error at the time of the crash. You can also run perfmon /rel to open Reliability Monitor.
macOS crash reports: In Finder, choose Go → Go to Folder and open ~/Library/Logs/DiagnosticReports/. Application logs may also be in a client-specific folder under ~/Library/Logs/. Some reports are available in Console as well.
Linux desktop environments: Run the client's actual executable from a terminal and capture standard error. If the client installs a user service, first use systemctl --user --type=service to find its service name, then check the corresponding logs.

Copy about 20 lines before and after the first error, not just the final “startup failed” message. For example, yaml: line 18 points to a configuration parse error, address already in use indicates a port conflict, and permission denied suggests a permissions or execution restriction issue. Retry messages at the end are often just a consequence of the earlier error.

3. YAML syntax errors: validate the config the core actually loads

If crashes began after updating a subscription, pasting rules, or switching profiles, check the configuration actually passed to the core. The client may combine a subscription, local overrides, and runtime options to generate a different file. Checking only the downloaded subscription can miss problems introduced during merging.

Check these four common issues first

Indentation: YAML uses spaces, not tabs. Align keys at the same level, and leave a space after the hyphen in list items.
Punctuation: Use a standard colon after each key. Quote node names or passwords that contain special characters, following YAML rules.
References: Policy groups referenced by rules, and nodes or other groups referenced by policy groups, must match their definitions exactly. Full-width parentheses and trailing spaces can also make names differ.
Core compatibility: Clash and Clash Meta (now called mihomo) differ in the fields and protocols they support. Valid syntax doesn't mean the current core supports every option.

If the client uses mihomo, test the configuration with the same core executable. Here's a Windows PowerShell example: first change to the directory containing the core, then copy the file you want to check to the current directory as config-check.yaml. Use the actual executable filename in the command.

New-Item -ItemType Directory -Force .\check-data | Out-Null
.\mihomo.exe -t -d ".\check-data" -f ".\config-check.yaml"
$LASTEXITCODE

-t tests the configuration, -f specifies the config file, and -d specifies the test data directory. Testing may also require resources such as GeoIP, GeoSite, or rule providers. If the error points to a missing resource, handle that separately rather than treating it as an indentation error. Exit code 0 means this test passed; it doesn't guarantee that ports are available, nodes can connect, or TUN can start.

4. Port conflicts: identify the listening process before changing ports

A common setup uses 7890 for the HTTP or mixed proxy port, 7891 for SOCKS, and 9090 for the controller, but these are not fixed standards. Check the current values for port, socks-port, mixed-port, and external-controller. The DNS listening port can conflict too.

Windows: find listening ports and their PIDs

Get-NetTCPConnection -State Listen -LocalPort 7890,7891,9090 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, LocalPort, OwningProcess

Get-Process -Id 1234

In the second command, 1234 is an example PID. Replace it with the OwningProcess value from the previous command. No results only means the checked TCP port wasn't listening at that moment; it doesn't rule out a UDP port conflict.

macOS: check a specific TCP listener

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

If another client instance is using the port, quit it normally from its tray menu and check for duplicate startup items.
If another application owns the port, temporarily change mixed-port in a local test config to 17890, then restart and test again.
After changing a port, also check your system proxy and any proxy settings configured separately in your browser. If you only change the core port, the system proxy may still point to 127.0.0.1:7890.

Don't terminate an unfamiliar system process, and don't expose the controller on a public address just to clear an error. A controller intended for local use should bind to the loopback address, such as 127.0.0.1:9090.

5. Missing core files, incompatible architecture, and TUN permissions

If the log says “file not found,” “cannot execute,” or “permission denied,” check the full core path shown in the log. An interrupted update, security software quarantine, or copying only the main program without its supporting files can leave the interface intact while preventing the core from starting.

Check the architecture: On Windows, find the system type under Settings → System → About. On macOS, check the chip under Apple menu → About This Mac. On Linux, run uname -m. Choose an installer that matches your system and the client's requirements.
Check quarantine history: On Windows, go to Windows Security → Virus & threat protection → Protection history and check the time and file path. Verify the file source and event details before repairing the installation. Don't disable system protection across the board.
Keep the full directory intact: Extract portable packages completely before running them. Don't launch the app from the archive preview or move a single executable out of the package.
Test TUN separately: If regular proxy mode starts but TUN fails, check service status, system permissions, and virtual adapter logs first rather than changing node passwords.

TUN typically requires extra system permissions or service support, depending on the platform and client. Turn off automatic TUN startup first and confirm the core runs reliably in regular proxy mode. Then restore TUN using the client's service installation or permission flow. A working regular proxy only confirms the basic path is back; it doesn't mean the TUN DNS and routing configuration is correct.

6. Roll back the config: isolate stale data in a separate copy

If the client still crashes after reinstalling, it may be reading the old data directory. The goal of a rollback isn't to delete everything right away. Instead, create a reversible test environment and see whether the problem follows the original configuration.

Rollback steps, one at a time

Close related processes: Exit the client normally and make sure no leftover core process is still writing data. If a background service is running, manage it through the client's service controls.
Back up the entire data directory: Keep profiles, subscription details, local overrides, rule files, and interface settings. You could name the backup clash-backup-2026-08-06. It may contain subscription credentials, so store it somewhere private.
Set the old directory aside: Confirm the actual data path, then rename the directory to preserve it. Some clients support portable or isolated data directories. Follow that client's instructions to create a test environment; don't reuse startup options from another client.
Create a minimal config: Turn off automatic subscription imports, overrides, and TUN. First verify config parsing and local listening only.
Restore components one by one: Restore the subscription, policy groups, rules, local overrides, and TUN in that order. Restore one item at a time, restart once, and record the result.

This config is for testing Clash or mihomo cores that support these fields. It uses 17890 as the mixed port, sends all traffic directly, and contains no proxy nodes. Save it as a separate local file without overwriting the original subscription. If that port is also in use, choose a free one using the steps above.

mixed-port: 17890
allow-lan: false
mode: rule
log-level: info

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

This config only checks basic startup; it can't tell you whether proxy nodes work. If it runs reliably but the original config fails as soon as you restore it, the problem is likely in the original config, an override, or a dependent resource. If this config also fails, keep checking the installation files, the graphical interface runtime, and system crash logs.

7. Verify the fix and prepare a useful bug report

One successful launch isn't enough to finish troubleshooting. Restart the client three times in a row and confirm the same error no longer appears. Then update the subscription once to make sure a remote config doesn't overwrite the local fix. Finally, restore the system proxy and TUN as needed, testing each separately so you can identify the source if something goes wrong.

Basic startup: The window opens normally, the core doesn't keep restarting, and the logs show no recurring parse or listening errors.
Listening status: The expected process owns each configured port, and the system proxy points to the correct port.
Config restored: You can identify the restored profile and local override, and the client still starts after a subscription update.
TUN restored: Enable it only if needed, and confirm system permissions, DNS resolution, and routing all work.

If you still need to report the issue, include the full client and core versions, operating system version and architecture, when the problem occurred, logs around the first error, and whether the minimal config starts. Redact subscription URLs, node passwords, controller secrets, and personal directory names. Keep the field hierarchy, error line numbers, and exception type so the issue can be investigated further.

Use this troubleshooting order: identify which component stopped, read the first error, test the actual config, check ports, inspect the core, and isolate old data. Before reinstalling, check platform support on the download page. For fields and rule relationships, see Advanced; for basic setup, see the user guide.