How to Fix Clash Client Crashes on Startup: Configuration, Permissions, and Stuck Processes

First distinguish a crash, background operation, and a hidden window

A Clash desktop client typically consists of a user interface, a proxy core, and system services. If no main window appears after double-clicking the icon, that does not necessarily mean all three components have exited. The interface may be minimized to the system tray, its window coordinates may still point to a disconnected monitor, or the proxy core may still be listening on a background port. The first troubleshooting step is not to keep launching it repeatedly, but to confirm its actual current state.

First check the Windows taskbar notification area, the macOS menu bar, or the Linux desktop tray. If you can see the client icon, use its menu to open the main interface. If you have used multiple monitors, remote desktop, or changed the display scale, also check whether the window is outside the screen boundaries. This is a window recovery issue, not a proxy core crash.

Next, open the system process manager and look for the client interface process, along with a process named Clash, mihomo, or the core process associated with your client. Use the following states to narrow down the cause:

• Both the interface and core processes disappear immediately: Check the startup logs, configuration parsing, runtime libraries, and local data first.
• The interface disappears but the core remains: Focus on interface logs, window state files, and the graphics runtime.
• The interface remains but the core keeps restarting: Check the YAML configuration, occupied ports, TUN permissions, and core version.
• The process remains but no window appears: Restore it from the tray first, then consider resetting the window layout. Do not delete all configuration files immediately.

Use logs to find where client startup stops

After a crash, logs are more reliable than a dialog box. Log locations vary by client, but they are usually near the user configuration directory, application data directory, or client installation directory. Filenames may contain app, main, service, core, or runtime. If the interface can still open briefly, check the actual directory in Settings or the Logs page first rather than deleting files based on another client's path.

When reading logs, start at the timestamp of the latest launch instead of searching for a single error. Some warnings do not prevent startup; the information that actually causes the exit is often in the last few lines. It is easier to locate the problem by following the startup stages:

1. The interface loads its settings and window state.
2. The current configuration file or the configuration generated from the subscription is read.
3. The Clash or mihomo core starts.
4. The mixed-port, HTTP, SOCKS, control, or DNS port is bound.
5. Rule providers, GeoIP, GeoSite, and other data are loaded.
6. The system proxy is installed, or TUN and system services are started.

If the log stops while reading the configuration, handle the YAML first. Messages such as address already in use or bind failed point to a port issue; permission denied or operation not permitted points to directory or TUN permissions; messages about missing dynamic libraries, WebView, or graphics components indicate an interface runtime problem. Do not blame subscription nodes for every error: unavailable nodes usually affect connectivity, not whether the client exits immediately before the interface finishes loading.

Check YAML configuration syntax and core compatibility

Configuration errors are a common reason the core exits immediately after starting. Clash configurations use YAML, so indentation, list nesting, and data types all affect parsing. Tab characters, full-width colons, missing spaces, unclosed quotes, and lists written as plain strings can all cause the core to reject the file. A subscription downloading successfully does not guarantee that its generated configuration is compatible with the current core.

Back up the current configuration first, then switch to the client's built-in basic configuration or a configuration previously confirmed to work. If the client starts normally, the problem is narrowed down to the current subscription, override script, or manual changes. Do not uninstall the client first: importing the same faulty configuration after reinstalling will reproduce the problem.

The following snippet shows nesting that is easy to confuse. Rules are a list of strings, and proxies inside a proxy group are also a list; both must use consistent indentation:

mixed-port: 7890
mode: rule
log-level: info

proxy-groups:
  - name: Manual selection
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

If you can run the proxy core directly, use its built-in configuration test option to check the file. A common mihomo test command is shown below; use the executable name and path from the actual client installation:

mihomo -t -f /path/to/config.yaml

The line number in the test result usually points near the parsing failure, but the cause may be in earlier lines. For example, if a quote is left open, the parser may not report the problem until the next field. Review the same configuration block above the reported line instead of changing only that line.

Fields that became incompatible after an update

Clash Meta was later continued as mihomo, and its supported configuration fields are not exactly the same as those of earlier Clash cores. Subscription conversion rules, TUN settings, enhanced DNS modes, rule provider formats, and proxy protocol parameters may depend on a specific core version. Passing a configuration generated for mihomo to an older core can produce errors such as unknown field, unsupported proxy type, or a failed rule provider load.

Conversely, updating the core may expose problems that an older version previously ignored. Confirm the core type and version currently used by the client, then check the subscription conversion target. Do not force startup by deleting unfamiliar fields at random: removing DNS, rule provider, or proxy parameters may let the syntax pass while changing the actual routing behavior.

Check runtime permissions, the configuration directory, and the TUN service

Standard system proxy mode usually does not require running the client as an administrator at all times, but writing to protected directories, installing system services, or creating a TUN network interface requires the appropriate permissions. Insufficient permissions may produce a clear message or cause some clients to exit during service initialization.

Windows users should make sure the client is not installed in a system directory that requires special write permissions, and check whether security policies are blocking the program from writing to its own configuration directory. If the client offers a separate service mode, reinstall or repair the service from the client settings instead of permanently relying on “Run as administrator.” A mismatch between the service and interface versions can also cause core startup failures or repeated reconnects.

macOS users should confirm that the app remains in a standard Applications directory and that Privacy & Security settings are not blocking its network extension or background items. Do not disable system security mechanisms to work around an app from an untrusted source; verify the installer source and use a build that matches the current system architecture. Linux users should check the configuration directory owner, executable permissions, and access to the TUN device.

Verify TUN mode separately

TUN mode creates a virtual network interface and modifies routing, so it requires more privileges than a standard HTTP or SOCKS proxy. If the log stops around tun, route, interface, or service, disable TUN temporarily and test with only the system proxy enabled. If ordinary proxy mode starts successfully, the YAML and interface are broadly working; the issue is likely in the TUN service, driver, permissions, or routing environment.

Disabling TUN is a diagnostic step only. When restoring TUN, check the client's service installation status, whether an old virtual network adapter remains in the system, and whether another VPN or network filter is also taking control of routing. Multiple networking tools can conflict through the routing table or DNS even when they use different ports.

Resolve port conflicts and leftover processes

The proxy core must listen on the ports defined in its configuration. Common ports include mixed-port, port, socks-port, external-controller, and DNS listen. If an old core has not exited or another proxy is using the same port, the new core fails during binding. If the client treats core termination as fatal, its interface may close as well, making it look like a crash immediately after double-clicking.

On Windows, first end the corresponding process in Task Manager, then use a command to check the specified port:

netstat -ano | findstr :7890

The PID at the end of the output can identify the process holding the port. On macOS and Linux, use:

lsof -nP -iTCP:7890 -sTCP:LISTEN

Do not terminate an unknown system process as soon as you see a port conflict. Confirm the program name associated with the PID first. If it is a Clash or mihomo process left by the previous launch, it can be terminated normally. If it is another service you still need, change the port in the client configuration and check that system proxy settings reference the new port.

Why leftover processes keep coming back

Some clients keep the core running after the interface exits to maintain the proxy connection; others fail to clean up after a crash. When launched again, the old core may still hold the port, control interface, or configuration file lock. The correct approach is to use the tray menu to exit completely, wait a few seconds, and then check the processes. If a process remains, terminate it with the system tools.

Restarting the system can clear ordinary leftover processes, but it cannot fix an old service that starts automatically. If the conflict returns after every boot, check the startup items and service list to make sure two different client versions are not launching automatically. Keep one entry for the client you currently use and manage the core service consistently from its settings.

Back up and rebuild damaged local data

When configuration syntax, permissions, and ports are all normal, check the state data saved by the client itself. An improper shutdown, interrupted disk write, or cross-version migration can damage the window layout, configuration index, database, cache, or settings files. Deleting the entire data directory may restore the program, but it also removes subscription records, override rules, and custom settings, so isolate the data layer by layer instead.

1. Exit the interface, core, and related services completely.
2. Find the data directory actually used by the client and copy it to a separate backup location.
3. Rename the window state, cache, or log directory first, then launch the client to test.
4. If it still crashes, rename the settings database or configuration index.
5. Let the client generate a new data directory and confirm that the main interface opens.
6. Restore only the subscription URLs and verified configurations you need; do not copy the entire directory back.

Renaming instead of deleting lets you roll back at any time and identify damaged files by restoring items one at a time. Data structures vary widely between clients, so filenames should not be assumed to match. In particular, interfaces based on Electron, WebView, or other desktop containers often store their cache and core configuration in different subdirectories. Confirm each location's purpose using the logs and client settings.

If the new data directory starts normally but the client exits again after importing the old subscription, return to the configuration compatibility checks. If restoring only the interface settings triggers the crash, focus on resetting the window layout, theme state, or local database. This limits the problem to one data type instead of repeatedly reinstalling everything.

Crashes after an update: check architecture, core, and runtime

When the client crashes on its first launch after an update, consider the application architecture, bundled core, operating system version, and configuration migration together. Windows installers may distinguish between x64, ARM64, and other architectures; macOS builds must distinguish between Intel and Apple Silicon. A mismatched build may fail to start or exit while loading the core. Confirm the processor architecture in system information, then choose the matching version.

Some desktop clients depend on the system WebView or specific runtime components. If the logs clearly identify a missing runtime component, repair it using the method specified by the operating system or client documentation. Copying dynamic library files from another computer can introduce version and architecture mismatches and is not a reliable long-term fix.

An in-place installation can also preserve an old core, service, or configuration migration marker. In that case, back up your data, remove the old program through the system uninstall process, and install the current version. Record subscription URLs, custom rules, ports, and DNS settings before uninstalling. After reinstalling, start with the default state and confirm that the interface and core work before restoring settings one by one.

If the new system no longer supports the current client, choose a Clash desktop client that is still maintained and compatible with that system. During migration, focus on configuration and core compatibility rather than comparing interface names alone. Some fields in a mihomo configuration require a matching core; when migrating an old Clash configuration to a new core, recheck DNS, TUN, and rule provider behavior.

Follow a fixed recovery process

The most common trap in crash troubleshooting is changing too many things at once. The sequence below starts with low-risk actions, and each step provides a clear conclusion. It applies to immediate exits, missing windows, crashes after updates, and repeatedly stopping cores.

1. Check the tray and processes: Determine whether the window is hidden, the interface has crashed, or the core has exited.
2. Fully stop old instances: Close the interface, core, and leftover services to prevent duplicate instances from competing for ports.
3. Read the latest log: Record the stage where startup stopped and the first meaningful error, not just the cascade of errors at the end.
4. Switch to the basic configuration: Use the client's default configuration to verify whether YAML or the subscription is the source of the problem.
5. Test ordinary proxy mode: Temporarily disable TUN to distinguish a core startup issue from a system networking or permission issue.
6. Check listening ports: Confirm that mixed-port, the control port, and the DNS port are not in use by another program.
7. Verify the application architecture and core version: Make sure the client, core, operating system, and configuration target are compatible.
8. Rebuild local state: Back up the data, then rename the cache, window state, and database one at a time.
9. Reinstall only as a last resort: Verify the default state first, then restore subscriptions and custom settings.

If the client still exits after these steps, save the client version, operating system version, processor architecture, core type, relevant logs, and reproducible steps. When reporting the issue, redact subscription URLs, node credentials, and control interface secrets, keeping only fields related to the error. Complete environment details help determine whether the failure is in the client interface, mihomo core, configuration generator, or system networking components.