Clash Startup Crash Troubleshooting: Config Errors, Port Conflicts, and Permission Issues

When a Clash client exits immediately after launch, the cause is usually not a single failure. The graphical interface, mihomo or Clash core, configuration, listening ports, and TUN components initialize in sequence. A failure at any stage may look like a brief flash of the window, a disappearing tray icon, or a process that ends after a few seconds. Repeatedly double-clicking rarely reveals anything new; first identify which layer is failing.

First distinguish a UI crash, core exit, and leftover background process

Startup failures usually fall into three categories. In the first, no window appears and no process is visible in Task Manager or Activity Monitor; focus on application files, execute permissions, and system security prompts. In the second, the interface appears and closes immediately, often because the config failed to load or the UI data is corrupted. In the third, the window disappears while a background process remains. The client may simply have minimized to the tray, or an old process may be holding a port required by the new instance.

Make an initial diagnosis in 60 seconds

1. Disable the system proxy and TUN mode so traffic does not continue reaching a dead port while you troubleshoot.
2. Open Task Manager, Activity Monitor, or the system monitor, then terminate leftover processes whose names contain Clash, mihomo, or the relevant client name.
3. Start the client again and watch how long the process remains active. If it exits in under 2 seconds, check execute permissions and application files first. If it runs for 2–10 seconds, check the config and ports first.
4. Check the logs in the client data directory. If the interface opens briefly, go to “Settings” → “Logs” or “Settings” → “Runtime Logs” and temporarily set the log level to info.
5. If the graphical interface leaves no logs, run the core directly in a terminal and test the configuration so the error output remains visible.

Config error: test YAML first, then restore a minimal configuration

Clash and mihomo read the YAML configuration before creating listening ports. Indentation errors, incorrect field types, incomplete rule entries, or proxy groups that reference missing nodes can all make the core exit immediately. If crashes began after a subscription update or manual config edit, put configuration checks first.

Common YAML errors

• Using tabs for indentation. YAML should use spaces, with matching indentation for fields at the same level.
• Missing a space after the colon, for example writing mixed-port:7890 instead of mixed-port: 7890.
• A rule is missing its policy name, for example DOMAIN-SUFFIX,example.com without a proxy group at the end.
• proxy-groups references a node or group that does not exist, especially after renaming a node without updating the group members.
• Full-width punctuation was introduced when copying content from a webpage, replacing the English colon, comma, or quotation mark.
• A mihomo-only field is being read by an older Clash core that cannot recognize the current configuration structure.

Test the configuration in a terminal

mihomo supports testing a configuration with -t and selecting a file with -f. On Windows, open PowerShell in the directory containing the core; on macOS and Linux, enter that directory in a terminal. These commands only test the configuration and do not keep the proxy service running:

# Windows PowerShell
& ".\mihomo.exe" -t -f ".\profiles\config.yaml"

# macOS or Linux
./mihomo -t -f ./profiles/config.yaml

# When using an older Clash core
./clash -t -f ./profiles/config.yaml

If the output includes a line number, check that line and the 3–5 lines above it first. YAML parsers often discover that the preceding structure is invalid only when they read the next field, so the reported line is not always where the problem starts. If the syntax test passes but the client still exits, check for runtime errors such as an empty proxy group, a failed provider download, or an unreadable ruleset path.

Use a minimal configuration to narrow the cause

Do not keep making changes to the original file. Copy the original config first, then create a temporary config containing only the port, mode, and empty rules. This verifies whether the core can complete a basic startup:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

If the minimal configuration starts, the core file and basic permissions are probably fine; the problem is likely in the original subscription or custom sections. Restore dns, proxy-providers, rule-providers, and tun one at a time, testing after each addition. If even the minimal configuration fails, move on to checking ports, permissions, and the core file.

Port 7890 is in use: find the process instead of only changing the number

mixed-port: 7890 tells Clash to accept both HTTP and SOCKS proxy connections on port 7890. If an old instance did not exit, another proxy application is running, or a system service already owns the port, the new core may report address already in use, bind failed, or similar text. Some graphical clients do not display this error, making the problem look like a startup crash.

Check port 7890 on Windows

Run the following commands in PowerShell. The first returns the process ID using the port; the second uses that ID to show the program name:

Get-NetTCPConnection -LocalPort 7890 -ErrorAction SilentlyContinue
Get-Process -Id 4321

Replace 4321 in the example with the OwningProcess value shown by the first command. You can also use built-in system commands to view listening entries:

netstat -ano | findstr :7890
tasklist /FI "PID eq 4321"

Check port 7890 on macOS and Linux

lsof -nP -iTCP:7890 -sTCP:LISTEN
ss -lntp | grep 7890

lsof works on macOS and most Linux systems, while ss is common on Linux. If the owner is an old Clash or mihomo process, exit it normally from the client first; only terminate the corresponding PID if it cannot exit. Do not kill an unfamiliar system service before confirming its executable path and purpose.

Keep three locations in sync when changing ports

If another program must keep port 7890, change Clash’s mixed-port to 7893, but make the configuration, client settings, and system proxy agree:

1. Set mixed-port: 7893 in the configuration file.
2. Go to “Settings” → “Parameter Settings” → “Port” and confirm that the mixed port is 7893.
3. Turn the system proxy back on and check that the HTTP and SOCKS addresses point to 127.0.0.1:7893.

Besides 7890, check 7891, 7892, and 9090. Older configurations often use 7891 for SOCKS, 7892 for redirection, and 9090 for the external control interface. A conflict on any required listener can also terminate the core. Use the ports actually enabled in the current YAML as the source of truth.

TUN startup failure: check the driver, service, and administrator permissions

A normal system proxy only needs a local listening port. TUN mode must also create a virtual network interface, change routes, and handle DNS, so it requires higher privileges. If the client runs reliably with TUN off but exits as soon as you enable “Settings” → “Network” → “TUN Mode,” the issue is usually the driver, service permissions, or a leftover virtual adapter.

Windows: check service mode and the Wintun interface

• Start the client once as an administrator to initialize the service or virtual adapter. Whether administrator privileges are required afterward depends on the client’s service mode.
• Go to “Device Manager” → “Network adapters” and look for a Wintun, Mihomo, or Clash virtual interface with a warning icon.
• If the client offers “Settings” → “Service Mode,” stop the old service first, then reinstall it to prevent the UI and background service versions from getting out of sync.
• Make sure Windows Internet Connection Sharing or other virtual networking software is not continuously recreating a conflicting route.

If the log shows Access is denied or operation requires elevation, the current process lacks the required privileges. If it shows device already exists, check for a leftover interface. If it shows start tun failed without more detail, set the log level to debug, retry once, then restore info to avoid generating excessive logs over time.

macOS: confirm network extension authorization

The first time a macOS client enables TUN, it may request a helper service installation or permission for a network extension. Open “System Settings” → “Privacy & Security” and check for a pending system software prompt at the bottom. Then open “System Settings” → “Network” → “VPN & Filters” and make sure the relevant configuration is not stuck reconnecting. If a client upgrade left the helper service out of sync, reinstall the service from the client settings instead of manually copying an old helper program.

Linux: check the TUN device and capabilities

First confirm that /dev/net/tun exists, then check whether the current account can create interfaces and modify routes:

ls -l /dev/net/tun
ip tuntap list
ip route
getcap ./mihomo

When run directly from a terminal, missing network-management capabilities may produce operation not permitted. With a systemd service, also check the service user, capability restrictions, and working directory. Do not run desktop-client TUN and another mihomo systemd service at the same time; they may compete for the interface name, DNS port, or policy routes.

Android and iOS: reauthorize the VPN

On mobile, TUN is usually implemented through the system VPN interface. On Android, go to “Settings” → “Network & internet” → “VPN,” remove the failed always-on connection, and authorize it again. Also check whether another VPN app is using the system’s single VPN channel. On iOS, go to “Settings” → “General” → “VPN & Device Management” to check the configuration status. If the system terminates the app as soon as it connects, also review battery optimization and background activity restrictions.

Missing or damaged core file: verify the path and reinstall the matching version

A graphical client is usually separate from the proxy core itself. At startup, the interface calls mihomo, Clash, or a bundled core file. If the core was moved, an upgrade was interrupted, or the architecture is incompatible, the interface may not find the executable or may receive an abnormal exit immediately after launching it.

First confirm which core the client actually uses

1. Open the client’s “Settings” → “Core” or “Settings” → “Version Information” and record the core name, version, and file path.
2. Check that the file at the specified path exists and that its size is not obviously 0 KB.
3. Run mihomo -v or clash -v directly in a terminal and confirm that it prints version information.
4. Check the system architecture. Windows and Linux commonly use amd64 or arm64; macOS on Apple silicon should use the arm64 build.

# Windows PowerShell
& ".\mihomo.exe" -v

# macOS or Linux
./mihomo -v
uname -m

If the version command also exits immediately, stop changing the subscription for now. Reinstall a client or core that matches the operating system and CPU architecture, then test with a minimal configuration. On Linux, also confirm that the execute bit is set; a readable file without execute permission returns Permission denied in the terminal.

ls -l ./mihomo
chmod u+x ./mihomo
./mihomo -v

If crashes began after a client update, also rule out an interface–core compatibility problem. Some newer configurations depend on mihomo fields that older cores cannot read; conversely, an older UI may not understand data returned by a newer core. For recovery, install the matching UI and core from the same release package instead of mixing files from different sources and versions in one directory.

Corrupted client data: rebuild the runtime directory while preserving the config

If the configuration passes testing, the ports are free, and the core runs independently but the graphical interface still crashes, the issue may be in the window state, database, cache, or client settings. You can rebuild the application data, but first back up the subscription URLs, profiles configs, custom rules, and scripts.

Safe rebuild order

1. Exit the client completely and confirm that no Clash or mihomo process remains in the background.
2. Copy the configuration directory to a desktop backup. Do not keep only the current YAML; provider files and custom rules may also need to be restored.
3. Rename the original data directory instead of deleting it immediately. For example, append -backup-20260722 to the directory name.
4. Restart the client and let it create a clean data directory.
5. Import one confirmed working configuration first instead of copying all old cached data at once.
6. Once startup is stable, restore subscriptions and custom rules one by one.

Windows application data is usually in a user AppData subdirectory, macOS commonly stores it in the user Library’s Application Support, and Linux commonly uses ~/.config. The exact directory name depends on the client. Confirm it through “Settings” → “Configuration Directory” or the home directory and config directory fields in the logs; do not delete a directory based on another client’s naming convention.

Follow the complete recovery process for your platform

Windows recovery steps

1. Disable the manual proxy under “Settings” → “Network & Internet” → “Proxy.”
2. End leftover client and mihomo processes in Task Manager.
3. Use PowerShell to check whether 7890, 7891, 7892, and 9090 are in LISTEN state.
4. Run the core version command and configuration test command in a terminal.
5. After the normal proxy starts, check service mode and the TUN virtual interface.
6. If it still fails, back up the data directory, reinstall the client, and restore only one verified configuration.

macOS recovery steps

1. Go to “System Settings” → “Network” and disable failed proxy or VPN configurations.
2. End leftover processes in Activity Monitor and use lsof to check listening ports.
3. Run the core from a terminal and verify the version and YAML configuration separately.
4. Check authorization prompts under “Privacy & Security” and the network extension under “VPN & Filters.”
5. If the normal proxy works but TUN fails, reinstall the helper service from within the client.

Linux recovery steps

1. Check whether the desktop client and a systemd service are running at the same time.
2. Use ss -lntp to inspect ports and journalctl to find why the service exited.
3. Confirm the core architecture, execute permissions, working directory, and permission to read the configuration file.
4. Test mixed-port with TUN disabled, then check /dev/net/tun and route permissions.
5. After fixing the issue, keep only one startup method to prevent two instances from loading the same configuration.

Post-fix verification checklist

A client that no longer crashes has only shown that the process can run. You must also confirm that the proxy path, DNS, and rule behavior have recovered. Verify them in the order below; if any step fails, stop at that layer instead of changing several options at once.

• The client runs continuously for at least 5 minutes with no recurring error entries in the log.
• Port 7890 or the custom mixed-port is listening, and the process name matches the current core.
• The system proxy address exactly matches mixed-port, for example 127.0.0.1:7890.
• After switching to rule mode, DIRECT, the proxy group, and MATCH resolve as expected.
• The subscription updates manually, and configuration testing still passes afterward.
• Enable TUN only after the normal proxy is stable, then check the virtual interface, default route, and DNS.
• Test once more after restarting the operating system to confirm that no old service is taking port 7890 or starting a duplicate core.

The most effective troubleshooting order is to preserve the error in a terminal, test the configuration, check the ports, and handle TUN and application data last. Configuration errors can usually be located by line number; port conflicts by PID; TUN failures by disabling TUN; and core problems through the version command and a minimal configuration. Change only one variable at a time so you know which action actually fixed the startup crash.