Clash Crashing on Startup? 6 Causes and Fixes

First, determine whether the window or the core has stopped

If Clash crashes as soon as you open it, don’t rush to reinstall. Desktop clients typically consist of a graphical interface, a proxy core, and background services. A disappearing window may simply mean the app was minimized to the system tray. If the window stays open but connections fail, the core may not have started. Each issue calls for different logs.

1. First, check whether the app icon is still in the Windows notification area or macOS menu bar. If you can reopen the main window from the icon, the app hasn’t crashed on startup.
2. On Windows, check the client and core processes in Task Manager → Details. On macOS, search for the app in Activity Monitor. Don’t judge whether a process is running based only on whether its window is visible.
3. Note the exact time you tried to launch the app, then save the application logs and system crash reports from that minute. Start with the first error; a final “process exited” message is usually just the outcome.

Work through the six causes below. The errors in the table are diagnostic clues; your client may show different wording.

1. Invalid config syntax

If the issue started after updating a subscription, editing an override, or switching configs, check the config first. YAML indentation must use spaces, with each level aligned. A missing space after a colon or a missing dash in a list can cause parsing to fail. Another common cause is using a config written for mihomo with an older Clash core: even valid YAML may use fields or rules the core doesn’t support.

Find the file the client actually loads

A client may combine subscriptions, overrides, and UI settings into a runtime config. So a subscription file that parses correctly doesn’t necessarily mean the final config can start. Check the config path in the logs. If the interface still opens, look in settings or config management for the data directory, runtime config, or logs. Menu names vary by client; don’t overwrite a file named config.yaml just because it happens to be in the installation directory.

For example, on Windows with mihomo, open PowerShell in the directory containing the core. If the config is at C:\ClashData\config.yaml and the data files are in the same directory, run:

.\mihomo.exe -t -d "C:\ClashData" -f "C:\ClashData\config.yaml"

-t tests the config and exits; -f specifies the config file; -d specifies the working directory. Replace these paths with your actual locations, and use the core bundled with your client. These are not universal launch arguments for every graphical client. Missing geodata or rule-provider files can also cause the test to fail, so check the error message for details.

• If the log points to line 20, check line 19 too. An unclosed quote on the previous line can trigger an error on the next one.
• If you see “policy not found,” check the rule target and policy group name character by character, including spaces and capitalization.
• If you see an unsupported rule type, check which core is running—don’t rely on the client’s name alone.

To recover, first disable recently added overrides or switch back to the last working config. If you’re unsure what a field does, consult the config reference. Don’t delete an entire DNS or rules section at once.

2. Core exits because a port is in use

Port conflicts often happen when two proxy clients run at once, an old core hasn’t exited, or a background service and manually launched core start separately. 7890 is often used as a mixed proxy port, and 9090 is common for the controller, but these ports aren’t fixed across all clients. Use the address and port shown in the logs when troubleshooting.

Find what’s using the port; don’t terminate an unfamiliar process

On Windows, run this command in a terminal. The last column shows the process PID:

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

Look for entries matching the local address and port with a state of LISTENING, then find the process in Task Manager → Details by PID. On macOS, you can use:

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

On Linux, use ss -lntp to check TCP listeners. You may need additional permissions to see processes owned by other users. If the error concerns a DNS UDP listener, check UDP as well—not just TCP.

1. If the port is held by an old client, quit it from its exit menu and check whether its background service is still running.
2. If you need to run two configs at once, assign different ports to each proxy and controller. For example, change one client’s mixed port to 7893.
3. Update your system proxy and browser’s manual proxy settings to match. If the core listens on the new port but the app still connects to the old one, the client may appear to start successfully while internet access fails.

If the log reports that access to a socket was denied, but no process is listening on the port, also check Windows excluded port ranges and security policies. Not every bind failure means another program is using the port.

3. Missing core file or incompatible architecture

If the interface opens but then reports that the core failed to start, common causes include an incomplete archive extraction, copying only the main executable, a stale core path after an app update, or security software quarantining the core. Some clients download the core separately; an interrupted download can leave the interface intact but the core missing.

• no such file or directory: Check the full path in the log and confirm the file exists. On Linux, the required dynamic loader may also be missing.
• exec format error: Check the architecture and file format first—for example, an ARM64 Linux core used on x86_64 Linux.
• “The specified file could not be found”: The missing item may be the core or one of its dependencies, not the main application.

Get the complete installer for your OS and architecture from the project’s official release channel, then use the client’s repair or reinstall process. On macOS, check your chip under Apple menu → About This Mac. On Windows, check System type under Settings → System → About. On Linux, run uname -m to distinguish x86_64 from aarch64.

If your system shows a quarantine record, first verify the file’s source and why it was flagged, then follow the system’s instructions. Don’t disable all security protections or replace the executable with a same-named file from an unknown file-sharing site. Clients and cores rely on compatible interfaces; mixing arbitrary versions can make startup problems harder to diagnose.

4. Insufficient permissions or a TUN service issue

A standard system proxy usually doesn’t require the client to run as an administrator at all times. Creating a TUN device, changing routes, or installing a background service may require elevated permissions. If the client starts normally with TUN disabled, check the service, virtual network adapter, and permissions before changing your subscription again.

Narrow down permission issues by platform

• Windows: Quit any duplicate instances, then use the client’s service management screen to check whether the service is installed and can start. Grant administrator access only when service installation or repair requires it. Also check whether the application data directory is read-only.
• macOS: Move the app to the Applications folder before launching it. If you’re asked to authorize a helper tool or see a system security prompt, verify the developer and source before allowing the requested action. Don’t use commands that broadly remove security attributes to hide the underlying problem.
• Linux: Launch the app from a terminal to see standard error output. If a trusted, manually downloaded core lacks execute permission, grant it to that file. For TUN, check whether /dev/net/tun exists and whether the service has the required permissions.
• Android: When enabling VPN mode for the first time, approve the system connection request. Usually only one VPN can be active per user or profile, so stop other VPN apps before trying again.

Also distinguish “can’t write config” from “can’t create a network interface.” The first usually appears in logs as a failure to write to a config, database, or log directory. The second typically occurs during TUN initialization. Running the entire interface as an administrator long-term won’t fix incorrect directory permissions.

5. Missing system component or runtime

If the app launcher reports a missing DLL, WebView, or shared library before application logs can even be created, check the interface’s runtime requirements first. Clash clients use different UI technologies: Electron, Tauri, and Flutter apps don’t share the same dependencies. Don’t install every runtime mentioned in a guide for a different client.

1. Windows: Note the full component name in the error. If WebView2 is explicitly missing, install the appropriate runtime from Microsoft’s official source. If the Microsoft Visual C++ runtime is missing, choose the architecture required by the project. Don’t download individual DLLs and copy them into a system directory.
2. macOS: Look for the process under Console → Crash Reports and check whether the macOS version is unsupported or the app failed to load for its architecture. Refer to the release notes for the current client version to find the minimum system requirements.
3. Linux: Launch the app from a terminal to see which shared library is missing. For software from a trusted source, use ldd to inspect dynamic dependencies. Prefer packages built for your distribution and install dependencies through its package manager; don’t manually replace core system libraries.

On Windows, press Win + R, enter perfmon /rel, and open Reliability Monitor to check for application failures around the same time. Keep the faulting module name and exception code, but a system DLL listed in the report doesn’t by itself prove that the DLL is damaged.

6. Corrupted cache or application state

An interrupted upgrade, sudden power loss, or migration between versions can corrupt window state, UI cache, or the local database. Symptoms include a blank window, the app closing immediately after launch, or a crash each time it restores the previous page. Cache cleanup can help later, but it shouldn’t be your first step.

Desktop: rebuild from a backup; don’t delete the whole directory

1. Quit the interface, core, and background services, then make sure no processes are still writing data.
2. Use the project docs or logs to find the actual data directory, then make a complete copy as a backup. Clients with similar names may still use different paths.
3. First try the client’s built-in cache cleanup or UI reset. If you can’t open the interface, rename only the cache or window-state files explicitly identified in the documentation, and keep them as a backup.
4. If you must rebuild the entire application data directory, first make sure your subscriptions and custom rules are backed up. Then rename the directory as a backup and let the app create a fresh one.
5. Once the app starts with a clean state, restore subscriptions and overrides one at a time. Don’t copy the old directory back wholesale.

Application data on Windows may be under %APPDATA% or %LOCALAPPDATA%; on macOS, commonly under ~/Library/Application Support/; and on Linux, commonly under ~/.config/. These are parent locations, not directories to delete as-is.

Android: Clear the cache and storage separately

On Android, go to Settings → Apps → select the client → Storage and cache, then try Clear cache first. Labels may vary by manufacturer. Clear storage or Clear data resets app data and may remove subscriptions, configs, and authorization, so back up everything first. If the installer has the wrong architecture or your Android version doesn’t meet the requirements, clearing the cache won’t fix the root cause.

Verify each step after recovery

Getting the window to open is only the first step. Restore features in this order: stabilize the interface, confirm the core is listening, test the proxy connection, then enable TUN. Verify each step before moving on so you don’t change several variables at once.

• Open and quit the client twice in a row, then check that no new crash reports have appeared.
• Start with a config you know works and leave TUN disabled for now. Check the logs for load failures or port binding errors.
• Enable the system proxy, confirm its port matches the core’s current listener, then test whether apps can connect.
• Finally, restore TUN, overrides, and automatic updates. If the issue returns at a particular step, troubleshoot the corresponding component.

If the app still crashes, include your OS version, CPU architecture, client and core versions, installer type, time the issue first occurred, and redacted logs when reporting it. Say whether it started after an update, config import, or enabling TUN. This is much more useful to maintainers than “it won’t open.” If you need to reinstall, confirm the OS and architecture on the download page first. See Getting Started for steps to restore your config.