Clash client crashes on startup: common causes and fixes

Don't delete your config or keep reinstalling just yet. If Clash closes as soon as you open it, first determine whether the UI process is crashing or the proxy core is failing to start. UI crashes are often related to the runtime environment, interface cache, or installer; core startup failures call for checking YAML, listening ports, core files, and permissions. A webpage failing to load is an outcome, not proof that the client has crashed.

1. Check whether the window, UI process, or core has exited

Many clients minimize to the system tray when you click the close button, so a missing window doesn't necessarily mean the process has stopped. On Windows, expand the hidden icons in the taskbar, then press Ctrl + Shift + Esc to open Task Manager. On macOS, check the menu bar icon and Activity Monitor. On Android, look for a persistent VPN notification in the notification shade.

On Windows, press Win + R, enter eventvwr.msc, then open Windows Logs → Application and check for application errors around the time of the crash. You can also run perfmon /rel to open Reliability Monitor. Note the faulting application, faulting module, and exception code. These details help narrow down the cause; seeing a system DLL listed doesn't mean you should delete or replace it.

2. Save the logs, then isolate YAML errors with a minimal config

Where to find logs and config files

If the UI still opens, check its Logs page first. In Settings, look for options such as “Open config folder” or “Open log folder.” Names and paths vary by client, so don't assume one product's directory applies to every Clash client. If the UI won't open, use the installation method and client documentation to locate the user data directory. Portable builds may store data beside the app; installed builds usually use a user data location.

Look for errors such as yaml, unmarshal, parse, permission denied, and address already in use. Start with the first meaningful error during startup. Later messages like “failed to connect to core” are often just a consequence.

Config validation is not a connectivity test

If you're using the mihomo core, you can run the PowerShell commands below from the directory containing the core. Make sure that directory actually contains mihomo.exe and the config.yaml you want to check. Bundled core filenames vary by client, so use the actual filename.

.\mihomo.exe -v
.\mihomo.exe -t -f .\config.yaml

Use -v to check the core version and -t to validate the config. A successful validation doesn't mean proxies can connect or that the required ports will be available during normal startup. Full configs that use external rule sets, subscription providers, or Geo data may also rely on data directories and resource files. Account for path differences when validating outside the client.

Common YAML problems include using tabs for indentation, omitting a space after a colon, incorrect list indentation, and treating a login or error page returned by a subscription URL as YAML. The line number in an error is a clue; the actual mistake may be on the preceding line. Quote passwords or URL parameters containing special characters such as # so they're not interpreted as comments or other YAML syntax.

Use a separate diagnostic file; don't overwrite your subscription

Save the content below as a separate diagnostic.yaml, then validate it. It contains no proxy nodes and is only for checking basic parsing and whether the startup environment works—not as a replacement for your everyday subscription.

mixed-port: 17890
allow-lan: false
mode: direct
log-level: debug
ipv6: false
tun:
  enable: false
dns:
  enable: false
rules:
  - MATCH,DIRECT

.\mihomo.exe -t -f .\diagnostic.yaml
.\mihomo.exe -f .\diagnostic.yaml

Before running the second command, fully quit the client and its background core to avoid interference from a duplicate instance. The command runs in the foreground; press Ctrl + C to stop it. If the minimal config starts but your original config doesn't, restore DNS, proxy providers, rule sets, and TUN one at a time, validating after each change. Don't change your subscription, core, and DNS all at once—you won't know which change fixed the problem.

3. Missing core files, the wrong architecture, or security blocks

A Clash client provides the graphical interface; Clash and Clash Meta (mihomo) are different implementations or branches in the core ecosystem. A working interface doesn't prove that its matching core is present. An older core may also fail to load a newer subscription if it doesn't support its fields or protocols. Don't “upgrade” every client by swapping in a random executable.

1. Make sure the installer was fully extracted. Don't run the app from inside an archive preview or copy only the main executable and leave out its resource folders. Back up user data before reinstalling, and follow the client's release instructions.
2. Check your system architecture. On Windows, go to Settings → System → About to see the system type; on macOS, check About This Mac for the chip; on Linux, run uname -m. x64, ARM64, and x86 builds aren't interchangeable.
3. Check security protection history. On Windows, go to Windows Security → Virus & threat protection → Protection history to see if the core was quarantined. Verify the publisher and the specific file before taking action; don't disable all security protection.
4. Update the core using a method supported by the client. Keep track of the client and core versions. If the problem started after a core change, roll back that change first rather than mixing and matching more files.

On macOS, “can't be opened” or “developer cannot be verified” warnings don't necessarily mean the process crashed. If you trust the source and your system allows it, check the relevant notice under System Settings → Privacy & Security. Follow your organization's policy on managed devices. On Linux, Permission denied may mean the file isn't executable, the directory isn't accessible, or the filesystem is mounted with noexec. Repeatedly rerunning the installer won't resolve these issues.

4. Insufficient permissions and TUN service issues

Standard HTTP/SOCKS proxies listening on high-numbered ports generally don't require the entire UI to run as administrator. TUN involves a virtual network adapter, routing, and DNS interception; desktop clients may need a service or privileged helper. If the error occurs only with TUN enabled, turn it off and test the regular proxy first to narrow the cause to the service or network interception.

• Windows: Check the client settings for Service Mode or TUN status. If it says the service isn't installed or available, repair it according to the client's instructions. Running as administrator once can help with diagnosis, but it isn't a substitute for properly installing the service.
• macOS: Make sure the required helper app has been authorized. If an authorization prompt appears after an app update, verify its permission status instead of manually removing system network components.
• Linux: TUN usually requires access to /dev/net/tun and the appropriate network administration permissions. In containers, device mapping and capability settings also matter, so standard desktop installation steps may not apply.
• Android: If system VPN permission is denied, the connection can't be established, but the app hasn't necessarily crashed. Disconnect other VPN apps, try connecting again, and approve the permission request. Work profiles and device management policies may also restrict VPN use.

5. A port conflict on 7890 is not a YAML syntax error

If the log shows bind or address already in use, the config may have parsed successfully but failed when binding to a port. On Windows, run the command below to check which process is listening on TCP port 7890. If nothing is listening, the first command may report that no matching object was found.

Get-NetTCPConnection -LocalPort 7890 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

netstat -ano | findstr :7890

The second command may show remote ports or other connection states, so check both the local address and connection state columns. Use the PID to identify the process under Details in Task Manager. On macOS, run lsof -nP -iTCP:7890 -sTCP:LISTEN; on Linux, run ss -ltnp 'sport = :7890'. You may need elevated permissions to see some process details.

If the port is held by a leftover instance of an older client, quit it using its normal exit option. If another necessary app is using the port, change mixed-port to a confirmed free port such as 7891, and update the system proxy and any browser manual proxy settings too. Also check port, socks-port, and external-controller separately; they can conflict as well, so don't focus only on 7890.

Some UIs regenerate their runtime config at startup. If an edit to a file on disk reverts after restarting, change the port through the client's settings or override feature instead of repeatedly editing a temporary generated file.

6. Runtime dependencies and UI cache: look beyond the config

Install dependencies based on the error; don't download individual DLLs

If Windows reports missing files such as VCRUNTIME140.dll or MSVCP140.dll, first repair the Microsoft Visual C++ 2015–2022 Redistributable as directed by the client, and choose the package matching the app's architecture. A 64-bit system can run 32-bit apps, so the required runtime depends on the app, not just the OS architecture.

Some WebView2-based clients rely on the Microsoft Edge WebView2 Runtime; that doesn't mean every Electron or Flutter client needs it. Install or repair it only when the logs or project documentation point to that dependency. “Install every runtime” isn't a universal fix. A Linux GLIBC version error usually means you need a build that supports your distribution; copying libc files from another system won't fix it.

Test for corrupted user data in a reversible way

If the core runs on its own but the UI still crashes during startup, fully quit the process, back up the client's user data directory, and rename it before launching the app again. It will create a fresh data directory. Don't delete the entire directory—subscriptions, rule overrides, UI state, and credentials may be stored in separate files.

If the fresh directory works, restore your subscription first, then rule overrides, and finally UI state and cache if needed. Copying all the old files back at once can bring the problem back too. If the logs point to a GPU process, try disabling hardware acceleration as documented by the client. Don't assume a startup flag for one UI works with every Clash client.

7. Verify each feature after recovery, and include these details when asking for help

Getting the window to open is only the first step. Work through these checks in order, restoring one feature at a time:

1. Make sure the UI stays open and the logs no longer show repeated core restarts or config parsing failures.
2. Verify that the active config is correct and still loads after a subscription update. Check whether an override reintroduced an unsupported field.
3. In Rule mode, test a browser request and check the connection log to confirm which rule and outbound route were actually used.
4. Enable TUN only if you need it, then test DNS resolution, wake from sleep, and network switching.
5. Quit the client and confirm that the system proxy settings are restored. If webpages still won't load after an abnormal exit, check whether the system proxy is still pointing to an old local port.

If the problem persists, share the client name and full version, core version, OS version, CPU architecture, what you did when the problem first appeared, and error logs from around startup. Also report whether a minimal config works, whether disabling TUN helps, and whether a fresh user data directory works. These results are usually more useful than a screenshot that just says “connection failed.”

For help checking config fields, see the YAML guide; for common network issues, see Troubleshooting. The key is to identify which layer is failing, then change the relevant setting—not to hide an undiagnosed problem with a reinstall.