How to Fix Clash Not Opening: Troubleshoot Startup Crashes and Instant Exits

Identify which startup step is failing

A Clash desktop client does more than launch a single process. The usual sequence is: the desktop shell loads the interface, then reads app settings and subscription configuration, starts the Clash Meta (mihomo) core, and finally binds the proxy port, control port, and optional TUN virtual network adapter. A failure at any stage may look like nothing happening after a click, a window that disappears immediately, or an interface that opens while the core repeatedly fails to start.

Before troubleshooting, fully quit any old processes. On Windows, open Task Manager → Details and end the client process and mihomo.exe; on macOS, search for the client name and mihomo in Activity Monitor; on Linux, use ps to find leftover processes. A vanished tray icon does not prove that the background process has ended. Repeatedly clicking the launch icon can create a second instance and another port conflict.

Keep files that can help identify the problem

Before resetting anything, copy your subscription configuration, hand-written YAML, rule sets, and logs. If the client still opens, check Configuration → Configuration File Directory and Settings → Logs. If the interface will not open, look in the system user-data directory. Common Windows locations include %APPDATA% and %LOCALAPPDATA%; on macOS, ~/Library/Application Support/; on Linux, ~/.config/. Directory names vary by client, so do not copy an entire directory over another client’s data.

Priority 1: rule out port conflicts and duplicate processes

Clash configurations commonly use 7890 for the HTTP or mixed proxy port, 7891 for SOCKS, and 9090 for the external control port. These are common defaults, not requirements. An older Clash installation, another proxy client, a development server, or a lingering mihomo process may already be using the same port. The core usually logs messages such as address already in use, bind, or “Only one usage of each socket address is normally permitted.”

Windows checks

Open PowerShell or Command Prompt and check the three common ports. The final column shows the process PID; use tasklist to identify the program:

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

After confirming that the PID belongs to an obsolete instance, first close it through that program’s own exit menu. If it will not quit normally, end the task in Task Manager → Details. Do not terminate a system process simply because it is listening on a port; another essential service may have been configured to use it.

macOS and Linux checks

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

If another proxy tool owns the port, close that tool or change the active Clash configuration. For example, temporarily change the mixed port from 7890 to 17890, and the control port from 9090 to 19090. Then update system proxy settings, browser extensions, and LAN devices so they use the new ports.

mixed-port: 17890
external-controller: 127.0.0.1:19090
allow-lan: false
mode: rule

Priority 2: check YAML configuration and subscription content

If the failure began immediately after updating a subscription, editing rules, or switching configurations, a parsing error is likely. YAML uses indentation to express hierarchy. Tab characters, a missing colon, a missing dash before a list item, or unquoted special characters can all stop the core during loading. Logs often mention yaml, unmarshal, mapping values, or a specific line number.

Validate the configuration directly with mihomo

If you can locate the mihomo executable, test the configuration from a terminal. -t tests the configuration, and -f is followed by the file path. Put the path in quotes if it contains spaces:

mihomo -t -f "C:\Users\Public\Documents\clash\config.yaml"

The macOS and Linux command is the same; only replace the path:

./mihomo -t -f "$HOME/.config/mihomo/config.yaml"

A successful test usually reports that configuration initialization completed; a failed test shows the field or line and column where the problem was found. Fix the earliest error first, because later messages may simply be cascading effects of the first indentation problem.

Common patterns that prevent startup

• Mixed indentation: Keep the same number of spaces at each level. Configure the editor to insert spaces instead of tabs.
• Missing proxy-group reference: Every policy name referenced by rules must exist in proxy-groups. Names containing spaces must match exactly.
• Duplicate proxy names: After manually merging subscriptions, multiple proxies entries may use the same name, which can break references.
• Wrong field type: port must be a number and allow-lan must be a Boolean. Do not replace them with lists or objects of a different structure.
• Wrong rule order: Put MATCH at the end of the rule list. It usually will not cause a syntax crash, but later rules will never be reached.
• Broken provider file: A valid main configuration does not guarantee that its proxy and rule collections are readable. Also check for failed downloads, changed paths, and invalid file formats.

The fastest way to isolate the issue is to start the core with a minimal configuration. The configuration below contains no nodes or subscriptions; it only checks whether the core can parse the file and listen on a local port:

mixed-port: 17890
mode: direct
log-level: info
allow-lan: false

proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

If the minimal configuration starts but the original does not, focus on the original YAML, generated subscription content, or an external provider. If the minimal configuration also fails, continue with ports, permissions, and the core itself. Keep a copy of the original file during testing; do not overwrite the only copy of a subscription with the minimal configuration.

Priority 3: address permissions, service mode, and TUN startup failures

A regular system proxy mainly listens on a local TCP port and needs relatively few permissions. TUN mode must also create a virtual network interface and modify routes and DNS, so permission problems are more common. Typical signs include a normal client interface and working system proxy, followed by a core exit after enabling Settings → TUN Mode. Logs may show permission denied, operation not permitted, failed to set route, or a virtual-interface creation failure.

Windows: verify service mode first

1. In the client, open Settings → Service Mode or System Service and check whether the service is installed and running.
2. If service installation fails, fully quit the client, then use the context menu to choose “Run as administrator.” Use elevated mode only to install or repair the service.
3. Open services.msc and check the status of the corresponding client service. The service name depends on the client; follow the name shown in its interface.
4. After repairing the service, start the client again as a regular user and test TUN. Avoid running the desktop interface as administrator on a permanent basis.

If an old client left behind a similar service after uninstalling, the new client may be unable to register its own service. Use the old client’s service-uninstall function first, then install the service component for the current client. Do not delete system network drivers in bulk based on their names, as this could affect VPNs, virtual machines, and container networking.

macOS: check network extensions and system permissions

When TUN or a system extension is enabled for the first time, macOS may require administrator approval. Open System Settings → Privacy & Security to review blocked-component alerts, and System Settings → Network → VPNs & Filters to inspect related network configurations. Moving the app to the Applications folder before launching it can reduce path and permission changes caused by running it from a temporary mounted location.

Linux: verify executable permissions and network capabilities

An AppImage needs execute permission before its first run. Set it in the file manager’s properties panel or run:

chmod +x ./Clash-Client.AppImage
./Clash-Client.AppImage

The capabilities required by TUN depend on the client’s service design. Some clients manage mihomo through a systemd service; others require separate network-capability setup. Prefer the client’s built-in service installer instead of running the entire graphical interface as root. If the log says /dev/net/tun does not exist, first check whether the system provides a TUN device:

ls -l /dev/net/tun
ip tuntap list
systemctl status NetworkManager

Priority 4: repair core files and version mismatches

The graphical client and the mihomo core are separate layers. A successful interface upgrade does not mean the core was replaced correctly. Security software quarantine, an interrupted disk write, an old process locking the file, or manually installing a binary for the wrong architecture can all make the client fail while starting the core. Common log signs include a missing file, execution denied, an abnormal process exit code, or an ARM64 build being used on an x64 system.

Confirm the system architecture

• On Windows, open Settings → System → About → System type to see whether the system is x64 or ARM64.
• On macOS, open the Apple menu → About This Mac to identify the chip. Apple silicon corresponds to arm64; Intel processors correspond to x64.
• On Linux, run uname -m; x86_64 corresponds to x64 and aarch64 to ARM64.

If the client offers Settings → Core → Redownload or Check for Updates, use that built-in option first. If the interface will not open, reinstall the complete client package that matches the system architecture. Quit the client and mihomo before installation so an old process does not lock the file being replaced. When copying only the core, also consider the APIs and configuration fields supported by the client; a large version gap can cause unrecognized fields.

You can check the mihomo version directly in a terminal. If version information is printed normally, the file is at least executable:

mihomo -v

If the terminal reports an invalid format or cannot execute the file, check the architecture first. If it says the file does not exist, check the core path recorded in the client settings. If the process exits immediately after starting, test it with a minimal configuration to separate a core-file problem from a configuration-loading problem.

Priority 5: install missing system components and reset app data

Some Windows clients use WebView2 for the interface, while others rely on Electron or another desktop runtime. If no window appears, the interface is transparent, or Event Viewer reports a WebView loading failure, open Settings → Apps → Installed apps and confirm that Microsoft Edge WebView2 Runtime is installed. If the client’s installation notes specifically require the Visual C++ 2015–2022 Redistributable, install the x64 or ARM64 version matching the app architecture.

Windows Event Viewer → Windows Logs → Application contains errors recorded at the time of a crash. Note the “Faulting application name,” “Faulting module name,” and exception code. If the faulting module is the client’s own executable, reinstall the client first. If it points to WebView or a system runtime, repair that component first.

Safely reset app data

If ports, configuration, permissions, the core, and runtimes are all working but the client still crashes while loading the interface, test a fresh app-data directory. Fully quit the program, rename the original data directory with a dated backup suffix—for example, from clash-client to clash-client-backup-20260818—and launch again. The client will create a clean initial data set.

1. If the new data directory starts successfully, the old directory likely contains a broken UI setting, database, or cache.
2. If the new data directory still crashes, the installation files, system components, or graphics-rendering layer are more likely to be responsible.
3. When restoring a subscription, import the configuration file only; do not immediately copy the entire old directory back.
4. Restart after restoring each item so you can identify which file reintroduces the failure.

For problems that began after an upgrade, also check whether both portable and installed versions remain. They may read different data directories while sharing the same ports and system proxy settings. Keep one clearly chosen installation, remove obsolete shortcuts, and open Task Manager → Startup apps to confirm that only the current client launches at startup.

Complete repair sequence by symptom

Case 1: No window appears after clicking the icon

1. Wait 10 seconds, then open Task Manager or Activity Monitor to check whether the process exists.
2. End leftover client and mihomo processes, then launch the client once.
3. Check system event logs for WebView2, runtime, or application-module errors.
4. Rename the app-data directory as a backup and start with fresh initial data.
5. If it still fails, reinstall a client matching the x64 or ARM64 architecture.

Case 2: The interface opens, but the core always shows as “Stopped”

1. Open the Logs page and find the earliest error entry; do not look only at the final line.
2. Check 7890, 7891, 9090, or the actual ports defined in the configuration.
3. Validate the current YAML with mihomo -t -f.
4. Test with a minimal configuration that uses 17890 as the mixed port.
5. Run mihomo -v to confirm the core file and system architecture.

Case 3: Only TUN mode will not start

1. Disable TUN first and confirm that the regular system proxy starts successfully.
2. On Windows, repair the client service mode; on macOS, check the network extension; on Linux, check /dev/net/tun.
3. Quit other VPNs, virtual network tools, and any second proxy client before testing again.
4. Check route, DNS, and interface errors in the logs, and record the exact interface name.
5. After repairing the service, restart the system and enable only one network interception tool.

Case 4: An update causes an immediate crash or core exit

1. Switch back to the last working configuration and pause automatic subscription updates.
2. Validate indentation, field types, and policy-group references in the new YAML.
3. Test the main configuration, proxy provider, and rule provider separately.
4. Delete failed temporary download files, then run the update once more.
5. Confirm that the fields generated by the subscription are supported by the current mihomo version.

After startup is restored, verify proxy operation

A client that opens successfully does not necessarily mean network interception is working again. After startup, confirm in the logs that configuration loading has completed and the proxy port is listening, then open the Proxies page and choose a policy group. Next, enable the system proxy under Settings → System Proxy, or enable TUN separately after the service status is normal. Do not change the configuration, DNS, TUN, and rule mode at the same time; otherwise it will be difficult to identify the source of a new problem.

Visit one site that should connect directly and another that should match a proxy rule. Watch the logs for the matched rule and policy-group name. If the interface works but every request fails, investigate node availability, subscription validity, DNS resolution, and rule matching instead of repeatedly reinstalling the client.