Clash Crashes on Startup: How to Find and Fix the Cause

First, determine whether the window or the core has exited

If the Clash client disappears as soon as you open it, that doesn't necessarily mean the entire application has crashed. Desktop clients typically include a graphical interface, a proxy core, and sometimes a separate service. After the window closes, the tray icon and core process may still be running. Or mihomo may fail to start while the interface remains open. Identify which component has exited before choosing a fix.

Record these four details before troubleshooting

• The client name and full version number. If the interface opens, check the About page; otherwise, look at the installer name or the application file's properties.
• Your OS version and architecture, such as Windows 11 x64 or macOS arm64. Avoid vague descriptions like “desktop.”
• The time the problem occurred, to the nearest minute, and whether you had just updated the client, imported a subscription, or enabled TUN.
• The full message shown before the client exited, and whether any client, mihomo, or related service processes are still running.

Get startup logs and system crash reports

Clash clients don't all use the same application data directory, so there's no single log path that applies to every client. If the interface still opens, check its Logs page or look in Settings for an option to open the log or application directory. The option's name varies by client and version. Save logs from about a minute before and after the failure, rather than capturing only the final “startup failed” line.

Windows: Event Viewer and app data

1. Press Win + R and enter eventvwr.msc.
2. Go to “Windows Logs” → “Application” and find entries from around the time of the failure. Application crashes often appear under the Application Error source with event ID 1000, but not every exit generates this entry.
3. Note the faulting application, faulting module, exception code, and application path. The path can help confirm whether you launched the newly installed version or an old shortcut.
4. In File Explorer, enter %APPDATA% and %LOCALAPPDATA% separately, then look for a directory matching the client name or project identifier. Logs may be in a logs subdirectory or in a location set by the client.

You can also run perfmon /rel to open Reliability Monitor and check application failures by date. System reports help diagnose graphical interface crashes; core logs are better for YAML, port, and resource-loading errors. Neither replaces the other.

macOS: diagnostic reports and Console

In Finder, choose “Go” → “Go to Folder” and enter ~/Library/Logs/DiagnosticReports/. Look for an .ips or .crash file matching the client process name and failure time. The app's own logs may be in a dedicated directory under ~/Library/Logs/ or ~/Library/Application Support/. Open Console to filter errors by process name, and note the exception type and termination reason.

Linux: launch from a terminal and check user logs

Run the installed client from a terminal to see standard error output that may be hidden when launching it from the desktop. Find the desktop launch command in the Exec field of the corresponding .desktop file. If the app or a user service writes to the journal, check the last ten minutes of entries:

journalctl --user --since "10 minutes ago" --no-pager

App data is commonly stored in project directories under ~/.config/, ~/.local/share/, or ~/.local/state/, but the exact location depends on the client. On systems using systemd, run coredumpctl list to check for crash records, if they were retained. No output doesn't necessarily mean the app didn't crash.

YAML syntax errors: validate the file the client actually loads

If the log mentions yaml, unmarshal, or a configuration line number, start with the Profile you just imported or edited. YAML indentation uses spaces, not tabs; keep fields at the same level consistently aligned. A successful subscription download doesn't guarantee valid configuration: an expired link may return a login page, an error message, or an unconverted list of proxies.

Check indentation, value types, and policy names

• mixed-port: 7890 is an example of a numeric field. A full-width colon or incorrect indentation can cause a parse error.
• List items need the correct - prefix. Writing rules as a plain string can cause a type conversion error.
• Policy names referenced by rules must match a proxy or proxy group in the configuration. For example, if a rule uses Proxy but the configuration defines only PROXY, check which name is correct.
• Check for duplicate fields and recently added merge or override settings. The original subscription may be valid even when the merged runtime configuration is not.

For a Clash client that uses mihomo, you can test a copy of the configuration after confirming the core's source and version. The example below assumes config.yaml is in the current terminal directory and mihomo is available as a command:

mihomo -v
mihomo -t -f ./config.yaml

If the core isn't in your PATH, use the full path to the core installed by the client. Don't download a different version to use as a substitute. Some configurations need to load rule resources or databases from a specific working directory; in that case, use -d to specify a working directory you've confirmed. Distinguish syntax errors, policy reference errors, and resource read failures in the test output.

The client may generate the final runtime configuration from Profiles, global overrides, and interface settings. So even if the original subscription passes validation, check the actual file the client loads. The clearest comparison is to restore a pre-change backup and restart without changing the client version. Don't permanently delete subscriptions or rules just to test.

Missing core files: check the installation and security history

If the log shows no such file or directory, a missing executable, or a failure to create the core process, check the exact path in the error. An interrupted update, moving the application directory, copying only the main executable, or security software quarantining a component can all leave an incomplete installation. Having the graphical interface files doesn't prove that the core and its dependencies are present.

1. Check the shortcut target and installation location to make sure you're not launching an old extracted copy.
2. Check that the core file exists and that the installer architecture matches your system. On Linux, Exec format error often indicates an unsupported executable format or architecture mismatch.
3. On Windows, open “Windows Security” → “Virus & threat protection” → “Protection history” and check for a quarantine event around the time of the failure.
4. Get the complete installer from the original project's release page, quit the client, then repair or reinstall it. Keep a backup of your app data, and don't mix loose files from different versions.

If a Windows error mentions WebView2Loader.dll or runtime initialization, the problem may be with the graphical interface runtime, not YAML. Only clients that depend on WebView2 need its runtime; don't apply the same fix to other clients. Follow the client's release notes to repair dependencies. Never download a DLL from an unfamiliar site and place it in a system directory.

macOS security blocks usually show a clear warning, unlike a silent crash. First check the app's source, system requirements, and diagnostic reports. Don't start by disabling Gatekeeper or removing security attributes from apps in bulk.

Permission issues: check directories and TUN separately

permission denied and access is denied mean an operation was blocked, but that doesn't mean you should run everything as an administrator. Reading and writing configuration files is a different permissions issue from using a TUN virtual network adapter: the former depends on file ownership and directory permissions, while the latter may require a privileged service, a system network extension, or device access.

Directory read or write failures

Start with the exact file path in the log. If the configuration is on read-only media, in a protected directory, or in a synced folder, the client may be unable to write its cache or database. On Linux, launching the graphical client with sudo may leave app data owned by root. Check the ownership of that directory instead of opening permissions across your entire home directory. Don't use chmod -R 777 as a fix.

TUN or service component failures

1. Restore the settings you had before enabling TUN, then check that the interface and regular proxy mode work normally.
2. Install or repair the service component using the current client documentation, then enable TUN from the client's interface.
3. Check for system prompts about authorization, blocked network extensions, or a service that failed to start, and save the relevant error.
4. Enable only one tool that takes over system routing at a time. Avoid running multiple virtual adapters and route managers simultaneously.

Lingering processes and port conflicts: identify the owner first

An old core left running after an update may occupy a port needed by the new core. The log message address already in use is more useful for diagnosis than a generic “startup failed.” Proxy listeners and external controller interfaces use different ports: 7890 and 9090 are common examples, but check your actual configuration and the port in the error.

Find the process using a port

On Windows, run the following command in Command Prompt. Note the PID in the last column, then check the process name and executable path under “Task Manager” → “Details”:

netstat -ano | findstr ":7890"
netstat -ano | findstr ":9090"

The output may also include matches for remote addresses. Check the local address, port, and listening state. On macOS, find the process listening on a TCP port:

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

On Linux, list listening sockets. Process details may be restricted, so an unprivileged user might not see processes owned by others:

ss -lntp 'sport = :7890'
ss -lntp 'sport = :9090'

1. Quit the old client from the system tray first. Stop a standalone service using its configured service manager; simply closing the window isn't enough.
2. Check the port again to confirm that it is no longer in use, then start the intended client.
3. If another essential service is using the port, change the target client's port and update system proxy and related app settings as needed.
4. End a process only after confirming who owns it. Don't terminate system or network components in bulk based on names that merely look like proxy software.

A port conflict usually prevents the core from starting, but doesn't necessarily crash the graphical interface. If the window still closes immediately after you free the port, go back to the system crash report instead of repeatedly changing ports.

Reset in stages after backing up

If the logs aren't enough to identify the cause, or old settings may not be compatible with a new version, test with clean app data. Reinstalling doesn't necessarily reset configuration because app data is often stored outside the installation directory. Before resetting, confirm which directory this client uses so you don't accidentally alter another client's data.

1. Stop the app. Quit the client from the system tray and make sure the core or service is no longer writing data.
2. Make a full backup. Copy the app data directory, including local YAML files, subscription details, override rules, and interface settings. Keep the backup with sensitive information in a secure local location.
3. Set the old data aside. Rename the confirmed app data directory—for example, add .backup-20260917 to the original directory name—instead of deleting it.
4. Start with default settings. Check whether the client can create a new directory and stay open. Don't restore automatic connection, TUN, or all subscriptions yet.
5. Restore items one at a time. Start with a configuration you've confirmed is valid, then restore override rules, and finally TUN and service settings. Check the logs after each step.

If the problem returns after restoring a particular item, you've found a repeatable way to reproduce it. If the client still crashes with fresh data, configuration is less likely to be the cause; check the client version, runtime dependencies, and system compatibility instead. If you roll back to an older version, use a separate backup so the old version doesn't read a database migrated by the newer one.

Verify the fix and prepare useful diagnostics

Getting the window to open is only the first check. Confirm that the core keeps running, the configuration loads successfully, and the listening ports match expectations. If you use the system proxy, check that browser requests go through the configured port. With TUN enabled, also check routing and DNS behavior. A proxy node timeout is a connection issue; it doesn't by itself mean the client is still crashing on startup.

• Fully quit the app and start it again to confirm the fix doesn't depend on a process left running.
• Save logs from before and after the fix, and note whether you changed the configuration, installation files, permissions, or service status.
• When reporting the issue, include the client and core versions, system architecture, reproduction steps, and the relevant error with sensitive details redacted.
• If the report includes a faulting module or exception code, copy it exactly. “It won't open” or a screenshot of the window alone isn't enough.

A useful troubleshooting order is: identify which component exited, collect logs, address configuration, files, permissions, or ports based on the error, then compare against a reset made after backing up. If you need a different installer, visit the client downloads page. For importing a configuration and setting up the system proxy, see the setup guide; for TUN and DNS options, see advanced configuration.