Clash Startup Crash Troubleshooting Checklist: Fix Port Conflicts, Configuration Errors, and Permission Issues

First determine whether the interface is closing or the Clash core is failing to start

“No window appears after double-clicking,” “the window disappears after one second,” and “the tray icon is present but the network does not work” may look similar, but they point to three different layers. A Clash GUI client typically consists of the interface process, the Clash Meta (mihomo) core, the system proxy, or a TUN service. If the interface process exits, the issue is with the client itself. If the interface remains open but the core repeatedly stops, check the configuration, ports, or core files. If the core runs normally but the network is unreachable, inspect the system proxy, DNS, rules, and TUN instead of repeatedly reinstalling the client.

Before troubleshooting, temporarily disable “Launch at startup” and “Silent startup.” If the client stays open briefly, go to Settings → General to disable startup launch, then copy the latest startup record from Tools or Logs. Menu names vary between clients; common paths include Settings → Logs, Tools → Application Logs, and Core → Runtime Logs. Focus on the last 20–50 lines before and after the exit time.

Step 1: Check whether ports 7890, 7891, or the controller port are already in use

Port conflicts are one of the most common causes of core startup failures. Typical configurations use HTTP port 7890, SOCKS5 port 7891, or combine both proxy entry points with mixed-port: 7890. External controllers commonly use 127.0.0.1:9090. These values are not mandatory standards, but two programs on the same device cannot listen on exactly the same address and port.

Check port usage on Windows

Fully exit the current Clash client, open PowerShell or Command Prompt, and run these commands in order:

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

If the results include LISTENING, the number on the far right is the PID. For example, 127.0.0.1:7890 may correspond to PID 8420. You can then inspect the process:

tasklist /FI "PID eq 8420"

After confirming that it belongs to an old Clash instance, mihomo, a proxy client, or a debugging service, close it normally from the original program’s exit menu whenever possible. Only terminate it with the command below after confirming that it has no other responsibilities:

taskkill /PID 8420 /F

Find listening processes on macOS and Linux

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

On Linux, you can also use ss:

ss -lntp | grep -E ':7890|:7891|:9090'

If both clients must remain running, open Settings → Network → Ports in one client and change its listening values—for example, set the mixed port to 7897 and the controller port to 9097. Then check the operating system’s proxy settings as well, so they do not continue pointing to the old 127.0.0.1:7890.

Step 2: Isolate YAML configuration errors from subscription problems

Clash Meta parses YAML during startup. Incorrect indentation, invalid field types, duplicate keys at the same level, and malformed rule formats can all make the core reject the configuration immediately. Common log messages include yaml: line 42, cannot unmarshal, proxy group not found, and invalid mode. Focus on the first configuration error instead of chasing every subsequent cascading message.

Use a minimal configuration to verify that the core can start independently

Back up the current configuration first, then create a test configuration containing only a local listener and direct-connection rules:

mixed-port: 7897
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups: []

rules:
  - MATCH,DIRECT

This configuration contains no subscription nodes and is not intended for daily proxy use. It verifies whether YAML parsing, port binding, and the core process can complete startup. If the minimal configuration works, the issue is probably in the original DNS, nodes, proxy groups, rules, or overrides. If the client still exits, continue checking the core file, directory permissions, and leftover services.

Restore sections gradually instead of pasting everything back at once

1. Restore the dns block first and restart the core to confirm that the fields are recognized by the current mihomo version.
2. Next restore proxies or the subscription providers, and check the node protocol parameters and certificate fields.
3. Add proxy-groups, confirming that every referenced node name, provider name, and other proxy group actually exists.
4. Restore rules last, paying particular attention to rule-set names, target policy names, and the final MATCH rule.

YAML indentation expresses hierarchy; tabs should not be mixed into space indentation. List items need a space after the hyphen, such as - MATCH,DIRECT. Boolean values, numbers, and strings cannot be exchanged arbitrarily. Node names containing colons, hash signs, or other special characters should be quoted; otherwise, everything after a hash sign may be treated as a comment.

proxy-groups:
  - name: "Manual Selection"
    type: select
    proxies:
      - DIRECT
      - "Node A"

If the failure began after a subscription refresh, switch back to the last known-good configuration on the Configurations page and disable automatic updates for comparison. A successful subscription download only means that the server returned content; it does not guarantee valid, parseable Clash configuration. A login page, HTML error page, or truncated YAML response may still be saved to disk, but the core will fail while loading it.

Step 3: Confirm that the mihomo core matches your system architecture

The GUI opening successfully does not guarantee that its core executable is usable. An interrupted update, security software quarantine, or manually replacing the core with the wrong architecture can cause it to stop immediately after you click “Start core.” Common Windows architectures are amd64 and arm64; Apple silicon Macs use arm64, while Intel Macs use amd64. Linux also requires the correct build, such as amd64 or arm64.

Open Settings → Core or Core Management and record the displayed core name and version. For example, a log entry such as mihomo v1.19.10 windows amd64 confirms that the file ran and reported its version. If no version information appears and the log only says “failed to start process” or “file not found,” check the file path and execute permissions.

Prefer the client’s built-in core management tools

• Disable the system proxy and TUN first to prevent an old core from keeping the file in use.
• Fully exit the client, then use Task Manager or Activity Monitor to confirm that the mihomo process has disappeared.
• Reopen the client and use Settings → Core → Check for Updates or Re-download to restore a core that matches your system architecture.
• After recovery, load the minimal configuration first and confirm that the core runs continuously for at least 30 seconds before switching back to the daily configuration.

When copying a core manually, do not determine its architecture from the filename alone. A wrong architecture may return “This app can’t run on your PC” on Windows or produce Exec format error on Linux. If macOS blocks the file because of developer verification or quarantine attributes, confirm its source and the client version first, then review the actual block record under System Settings → Privacy & Security instead of repeatedly double-clicking it.

Step 4: Handle permissions, the TUN service, and protected directories

A standard system proxy usually only needs to listen on a high-numbered local port, while TUN mode must create a virtual network interface, modify routes, or call a system service, so it requires higher privileges. A typical symptom is that the client remains stable with TUN disabled but the core exits immediately after TUN is enabled. Treat TUN as a separate variable during troubleshooting.

Windows: distinguish application permissions from service permissions

Running the client as administrator can help with a one-time diagnosis, but it should not be treated as the universal fix. If TUN works when launched as administrator but fails normally, open Settings → TUN Mode or Service Mode in the client and reinstall its system service. Then exit the administrator session and test again normally.

Also check whether the application is installed in a directory that requires extra write permissions. Runtime data should not be written to a read-only location under C:\Program Files, and the client should not be run directly from a compressed archive preview window. Fully extract the program to a user-writable directory, such as a dedicated application folder in your user directory, before launching it.

macOS and Linux: check execute permissions and network capabilities

If a manually deployed Linux core lacks the execute bit, it will return Permission denied immediately. Check its permissions first:

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

This only fixes file execution permissions; it does not automatically grant the capabilities required to create a TUN device. When using TUN through a desktop client, prefer the service installation flow provided by that client. When deploying through systemd, check the service unit’s user, network capabilities, working directory, and configuration path. Do not run the desktop client while also starting another systemd service that listens on the same ports.

On macOS, check System Settings → Privacy & Security for blocked system extensions or applications, and System Settings → Network for duplicate VPN configurations. After making changes, fully exit and restart the client so an old network extension state does not affect the test.

Step 5: Clean up leftover processes, lock files, and duplicate startup entries

After the client window disappears, the mihomo core or a system service may still be running in the background. A new instance can then encounter a port conflict, database lock, or “another instance is already running” message. On Windows, check the client’s main process, mihomo.exe, and the older clash.exe on Task Manager’s Details tab; use Activity Monitor on macOS; on Linux, run:

ps -ef | grep -E 'mihomo|clash'
systemctl --user status mihomo
systemctl status mihomo

If the same program is configured as a system service, a user service, and a desktop startup item, it may launch two or three times at login. Keep only one startup method. On Windows, check Settings → Apps → Startup and Task Manager’s Startup apps; on macOS, check System Settings → General → Login Items; on Linux, check both systemd services and the desktop environment’s autostart directories.

Only handle lock files after confirming that all related processes have exited. Do not delete databases, caches, or runtime directories while the core is still running. If the client offers Reset Runtime State or Clear Cache, use the built-in function first. If rebuilding user data is unavoidable, back up subscription URLs, local YAML, rule overrides, and app settings, then rename the original directory to preserve it instead of deleting it permanently.

Step 6: Follow a fixed sequence for a reproducible diagnosis

Crash troubleshooting becomes slowest when five settings are changed at once. The sequence below starts with low-risk, easy-to-verify checks, changing only one variable at each step:

1. Fully exit the client and confirm that no interface, mihomo, or clash processes remain.
2. Check the actual configured ports, including 7890, 7891, and 9090, then close conflicting processes or change the ports.
3. Disable TUN, system services, and startup launch, leaving only the standard mixed-port enabled.
4. Load the minimal YAML and observe whether the core remains stable for at least 30 seconds.
5. Record the core architecture and version, then redeploy it once through the client’s core management entry.
6. Restore DNS, nodes, proxy groups, and rules section by section, restarting and checking the logs after each change.
7. Re-enable the system proxy last, then test TUN and startup launch.

For every test, record the “action, result, and last error log.” For example: “Changed the port from 7890 to 7897; the minimal configuration ran normally for 60 seconds. After switching back to the subscription, a parsing error appeared on line 184.” Notes like these quickly narrow the issue to the configuration instead of vaguely blaming the client version.

When should you reinstall the client?

Reinstallation is reasonable only when the interface process itself will not open, application files are missing, built-in core management cannot recover the core, or the user data directory continues to report read/write errors even with the minimal configuration. Before reinstalling, disable the system proxy and TUN service, back up necessary configurations, and uninstall the old version. After installation, do not immediately import all old data: launch once with default settings, then import a configuration already confirmed to be valid.

When is reinstallation unnecessary?

• The log clearly says address already in use: resolve the port conflict.
• The log provides a YAML line number: fix the configuration structure or switch back to a working configuration.
• Failure occurs only when TUN is enabled: address service permissions, drivers, or routing conflicts.
• The client began exiting after a subscription update: roll back the configuration and inspect the subscription response.
• A mihomo process is already running in the background: stop the duplicate instance and clean up startup entries.