Clash Crashes on Startup? How to Find the Cause in Logs and Fix It

First, identify what’s closing: the window, the core, or the entire client

If no window appears after you double-click the icon, Clash may not have crashed. Desktop clients typically have three parts: a graphical interface, a proxy core, and an optional background service. The window may be minimized to the system tray, or the interface may be running while the mihomo core exits because of a configuration error. Identify which part failed before trying a fix.

1. Check the system tray or menu bar. On Windows, expand the hidden icons beside the taskbar. On macOS, check the menu bar at the top of the screen. If the icon is there, try “Show Main Window” first. Don’t launch multiple copies.
2. Check running processes. On Windows, open Task Manager → Details; on macOS, open Activity Monitor; on Linux, use your system monitor. Check whether the client process and core processes such as mihomo are still running.
3. Note when the problem occurs. If the app stopped opening after an upgrade, exits after a subscription update, or quits when you enable TUN, the likely causes are the app environment, configuration, or permissions, respectively.
4. Close duplicate instances, then try again. Quit from the system tray, then confirm the process has ended. A background service may still be running, so closing the window alone doesn’t mean the app has fully exited.

Find the startup logs on each platform

If the interface still opens, look in Settings for options such as “Open Logs Folder,” “Open Config Folder,” or “Open App Directory.” Interface logs often include core output, but may not capture a crash in the interface itself. If the app won’t open at all, check the system crash reports too.

Windows: check the faulting module, not just “Application Error”

Press Win + R, enter eventvwr.msc, then filter Application events by the time of the crash. Event ID 1000 often indicates an application crash; 1001 may include Windows Error Reporting details. These are clues, not definitive causes. Note the “Faulting application name,” “Faulting module name,” and “Exception code,” then compare them with the client logs.

Linux and Android: capture output you can reproduce

On Linux, run the client’s actual executable from a terminal. If you use a user-level systemd service, check its logs from the last ten minutes. The Android command below requires ADB to be installed, USB debugging enabled, and your computer authorized. Run it immediately after reproducing the crash:

# Linux: view user-session logs
journalctl --user --since "10 minutes ago" --no-pager

# Android: export the crash buffer to the current directory on your computer
adb logcat -b crash -d > clash-crash.txt

Before sharing logs, redact tokens in subscription URLs, node passwords, UUIDs, control interface keys, and any access domains you don’t want to make public. Sharing about 30 lines around the error is usually more useful—and reveals less—than uploading the entire config folder.

Cause 1: Invalid YAML or a config incompatible with the core

If the issue started after editing the config, updating a subscription, or changing cores, look for messages such as yaml:, unmarshal, proxy group, or not found. YAML uses spaces for indentation; tabs aren’t valid substitutes. A missing space after a colon or a misaligned list can make parsing fail.

• Syntax errors: If the log says line 18, check line 18 and the lines just before it. The reported location may simply be where the parser could no longer continue.
• Reference errors: A proxy group may refer to a node that doesn’t exist, or a rule may refer to an undefined proxy group or rule set. These are configuration logic errors; changing indentation alone won’t fix them.
• Core incompatibility: Clash, Clash Premium, and Clash Meta (now called mihomo) support different features. Whether a protocol or config field works depends on the core that actually starts and its version—not just the client’s branding.
• Unexpected download content: An expired subscription URL may return a login page or an error message. Check whether the file starts with HTML; don’t import a server error page as YAML.

Test the config with the same core

Make a copy of the config before checking it; don’t edit a file generated by a subscription directly. If your client uses mihomo, run the actual core to test the config. If it references relative paths, use the original working directory as well. The example below is for Windows PowerShell: first go to the directory containing the core and have the required files ready.

.\mihomo.exe -v
.\mihomo.exe -t -d "C:\Clash-Debug" -f "C:\Clash-Debug\config.yaml"

Use -v to check the version and -t to validate the config. Put the config and any required local rule files in the test directory before running the command. Missing resources or failed remote downloads can also cause the test to fail, so don’t assume every failure is due to YAML indentation. A successful test confirms only that this check passed; it doesn’t guarantee TUN permissions, port binding, or network access will work.

Cause 2: Port 7890 or the controller port is already in use

If the log says bind: address already in use, or Windows reports that each socket address can only be used once, check the listening ports. The mixed port is commonly 7890 and the controller port is often 9090, but both can be changed—check your current config. A port conflict usually prevents the core from starting, but doesn’t necessarily close the entire graphical interface.

# Windows PowerShell: filter listeners by the port in use
Get-NetTCPConnection -State Listen -LocalPort 7890,9090 |
  Select-Object LocalAddress,LocalPort,OwningProcess

# macOS: check which process is listening on TCP port 7890
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: list TCP listening ports and processes
ss -ltnp

On Windows, use Get-Process -Id process_id to look up the PID shown in the previous step. Common causes include another proxy client, an old core process, or a service that’s still running. Identify the process before exiting it through the appropriate app. Don’t force-quit a system process just because it’s using a port.

1. Quit other proxy clients and any background services you no longer need, then restart Clash once.
2. If you need to run both programs, change one mixed port to an unused port, such as 7897, then check the listener again.
3. Update the proxy settings in browsers, terminals, and LAN devices where you entered them manually. If you change only the core’s port, apps using the old proxy address may lose network access even though the client starts.

permission denied or “An attempt was made to access a socket in a way forbidden by its access permissions” doesn’t mean the port is already in use. It may indicate a reserved port, a security policy, or insufficient permission to bind. Check the full error for more detail.

Cause 3: Missing core files, wrong architecture, or an incomplete installation

If you see no such file or directory, failed to spawn, or exec format error, first check that the app is installed completely. Some distributions package the interface and core separately; copying only the main executable may leave out bundled resources and helper programs.

• Check the architecture: On Windows, go to Settings → System → About and check System type; on macOS, check the chip under About This Mac; on Linux, run uname -m. Builds for x86_64 and aarch64 are different and aren’t interchangeable.
• Check how it was installed: Fully extract archives to a permanent folder before running the app. On macOS, copy the app to Applications and launch it from there rather than running it from a disk image.
• Check security software: On Windows, open Windows Security → Virus & threat protection → Protection history. Verify the file’s source and detection details first; don’t disable all protection just to launch the app.
• Reinstall the program files: Get an installer that matches your system from the project’s official release channel. Keep your user data; don’t combine reinstalling the app with deleting its config.

On Linux, a “file not found” error can mean the dynamic loader or a dependency is missing, even if the target file exists. For binaries from a trusted source, use file to check the architecture, then investigate any dependency errors in the terminal. A normal-looking file size doesn’t prove the program is complete or runnable.

Causes 4 and 5: TUN permissions, service issues, and missing runtimes

If it exits only when TUN is enabled, test with regular proxy mode first

TUN creates a virtual network interface and changes routes; some configs also take over DNS. These operations often require elevated permissions. If the app starts normally with TUN disabled, check its service mode or privileged helper instead of repeatedly changing subscriptions.

1. Quit other VPNs or proxy tools that are managing network traffic, then test with just one client running.
2. If the interface opens, turn off TUN and restart the app to check whether regular proxy mode works.
3. Use the client’s built-in install or repair option to fix the service, and check that it points to the current installation directory. After moving a portable version, an old service may still point to the original path.
4. On macOS, check authorization for the privileged helper. On Linux, look for permission errors in the service logs. Don’t make the entire config folder writable by everyone or run the graphical interface as root long-term to work around the issue.

On Android, a denied VPN permission or another app using the VPN connection usually causes a connection failure, not an app crash. Continue troubleshooting a crash only if the system crash report confirms that the app itself failed.

Blank or briefly flashing window? Check the interface runtime

Different interface technologies have different dependencies. Windows clients built with Tauri usually require Microsoft Edge WebView2; Electron clients typically include their own Chromium runtime. Don’t assume every blank window is caused by WebView2. Check the client’s release notes for requirements, then install or repair the relevant component from Microsoft.

If you see a missing VCRUNTIME140.dll or MSVCP140.dll error, install the Microsoft Visual C++ Redistributable required by the app and match its architecture. Don’t download individual DLL files from DLL sites. On Linux, install missing shared libraries using your distribution’s package manager and the project’s dependency instructions. Don’t copy libraries from untrusted sources into system folders.

Safely reset the config: rename it to set it aside instead of deleting it

If config checks don’t reveal the cause, or the client crashes when loading old interface state after an upgrade, try starting with fresh user data. This can affect subscriptions, rule overrides, proxy group selections, shortcuts, services, and TUN settings, so check the logs first.

1. Export or copy your data first. Save subscription sources, local configs, rule overrides, scripts, and client settings. Backups may contain credentials, so keep them somewhere secure.
2. Quit completely. Exit from the system tray and confirm that the core processes have stopped. If you need to manage a service, use the client’s service management option.
3. Set aside the actual user data folder. Confirm it belongs to the client you’re using, then rename it—for example, append .backup-20261021. Don’t rename the entire AppData or .config folder.
4. Start with default settings. If the app opens, leave TUN disabled, import a config you know works, and test startup and shutdown.
5. Restore items one at a time. Restore the subscription, rule overrides, interface settings, and TUN in sequence, restarting after each change. Don’t copy the entire old folder back, or you may bring the problem back too.

If the app still crashes with fresh data, focus on the build, runtime environment, or system compatibility. Repeatedly resetting the config is unlikely to help. Keep your backup, test another compatible version according to the project’s release notes, and avoid letting an older version write to a newer version’s data directory.

Checklist before reporting the issue

When asking for help, replace “it won’t open” with steps that reproduce the problem. The details below help maintainers determine whether the issue is with the interface, core, or system environment—and reduce the need for follow-up questions.

• Client name and full version; core name and version; OS version and CPU architecture.
• Installer type, whether the installation directory was moved, and whether you upgraded from an older version.
• Steps to reproduce, such as “exits 2 seconds after launch” or “exits immediately when TUN is enabled.” Describe what you observed, not a suspected cause you haven’t confirmed.
• When the crash occurred, relevant logs, the system crash module, and the full config test error.
• What happened after disabling TUN, stopping other clients, and using a fresh data directory?

After fixing the issue, verify the full workflow: the main window opens repeatedly; the proxy core keeps running; the local port is listening; apps with manually configured proxies use the correct port; and the system proxy is cleared after a normal exit. If you used TUN, test enabling and disabling it separately. This confirms that the proxy is working—not just that the window appears.