Clash Startup Logs: Tell a Window Exit from a Core Exit

If the window disappears after you open the client, first check whether its icon is still in the system tray or menu bar. Some clients keep running in the background after the window closes; others leave the window open but show a connection failure because the core process has exited. Note when you click Launch, retry just once, then compare the app logs, core logs, and system records from that same time. This helps keep errors from separate launch attempts from getting mixed up.

  • The window is still open: If the client has separate “Logs” and “Core logs” views, start with the earliest error in the core logs. Then check the app logs to see whether they show the core executable path and the configuration file actually loaded.
  • The Windows window flashes and disappears: Open “Event Viewer” → “Windows Logs” → “Application” and look for errors around the time of launch. If you find an “Application Error” entry, check the names of the faulting application and module to tell whether the client itself or the core exited. A routine configuration load failure may not appear here.
  • The macOS window flashes and disappears: Open “Applications” → “Utilities” → “Console” and look for a crash report from the time of launch. If there isn’t one, check the startup logs saved by the client. Some processes print an error and exit normally, without generating a crash report.
Log excerptWhat to check next
yaml: line 12Open the YAML file that was actually loaded and check indentation and list structure above line 12.
address already in useUse the address, port, and protocol from the same log entry to identify the listening process.
no such file or directoryFirst identify whether the missing item is the core, configuration, or a rules file, then check the full path in the error.
exec format errorCheck the core file format and make sure the package matches your operating system and processor architecture.

YAML Configuration Errors: Check the Field Before the Reported Line

A log pointing to line 12 doesn’t necessarily mean line 12 is wrong. For example, if a string’s opening quote is missing on line 11, the parser may not report an error until it reaches the next line. Open the file at the path shown in the log using a plain-text editor with line numbers and whitespace characters visible. Clients that merge subscriptions or apply overrides often load a generated configuration, not the original subscription file. Use the generated file to locate the problem, then fix the local override or subscription source so an update doesn’t overwrite your changes.

Check the syntax first, then verify references

  1. Align fields at the same level and use spaces, not tabs, for indentation. Leave one space after the colon in key-value pairs such as mixed-port: 7890. Check the previous two or three lines for an unclosed quote and make sure each list item has a -.
  2. If the file starts with <!doctype html>, you may have downloaded a login or error page. Check the subscription source and output format. Don’t try to fix a webpage as YAML, and never post a subscription URL containing an access token in a public support thread.
  3. If the log says a proxy group or rule set doesn’t exist, check that the target at the end of the rule matches a name under proxy-groups, and that each RULE-SET reference matches a key under rule-providers. Valid YAML syntax doesn’t guarantee that references are valid. If you’ve switched from mihomo to an older Clash core, also check that the version supports the fields and rule types you’re using.

Isolate subscriptions and overrides with a minimal local config

Export the config from the client, or back up the original after quitting the client. Save the lines below as test.yaml without overwriting your active subscription. This example listens on a mixed proxy port on localhost only; all matching traffic is sent direct, and no proxy nodes are tested. If port 7890 is already in use, confirm an available port as described in the next section before testing startup.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
  - MATCH,DIRECT

If you have a standalone mihomo executable of the same version, use -t to check the configuration. The example below runs in Windows PowerShell and assumes the current directory contains mihomo.exe, test.yaml, and an empty directory named clash-test-home for this test:

.\mihomo.exe -t -d .\clash-test-home -f .\test.yaml

Here, -d sets the core’s working directory, and -f specifies the configuration file. Even if the test passes, start the core normally once to confirm that the port binds and the client’s launch flow works. When testing your original config, switching to an empty directory may trigger separate missing-file errors if it relies on rules or other resources in its working directory. Don’t mistake those errors for YAML syntax problems.

Port 7890 Is in Use: Identify the Process by Address and Protocol

mixed-port is the shared listening port for HTTP and SOCKS proxies; external-controller is the address for the control interface. The error could also come from a DNS listening address. If the log says listen tcp 127.0.0.1:7890, check TCP port 7890. If it reports a control interface at 127.0.0.1:9090, changing the mixed port won’t resolve the control-interface conflict. Also check wildcard addresses such as 0.0.0.0:7890, which may already cover the loopback address.

Windows: Find the listening entry, then check the PID

netstat -ano -p tcp | findstr ":7890"

Check whether the “Local Address” column ends in :7890 and the state is LISTENING. Results may also include connections where the remote port happens to be 7890; those entries don’t indicate a local port conflict. The last column shows the PID. Find the matching process under “Task Manager” → “Details.” If the error mentions UDP, run netstat -ano -p udp and check the matching local port. UDP results don’t have TCP’s listening-state column.

macOS: List TCP listeners directly

lsof -nP -iTCP:7890 -sTCP:LISTEN

Identify the process from the COMMAND and PID columns. For a UDP port, use lsof -nP -iUDP:7890, replacing 7890 with the port shown in the log. A standard user account may not show every process; an empty result could also mean the process has already exited, so check as soon as the error occurs.

Missing Core Files: Check the Path, Package, and System Architecture

The client interface and proxy core are separate components. Seeing the app icon doesn’t mean the core file it needs at startup is still there. With a portable release, extracting only the main program from the archive or upgrading while still pointing to an old directory can leave the interface unable to find the core. If the log reports that a child process failed to start, first check whether the path points to an executable. If it points to a ruleset, geodata, or configuration file, restore that resource or fix the working directory rather than replacing the core.

  1. Check the file location. Look for the file at the full path shown in the log. Extract portable packages in full to a local directory and preserve their original folder structure. For an installed version, use the same client’s release package to repair it; don’t rename another client’s core and drop it in.
  2. Check the operating system and architecture. On Windows, open “Settings” → “System” → “About” and check “System type” to distinguish x64 from ARM64. On macOS, use the Apple menu → “About This Mac” to identify an Apple silicon or Intel processor. When the release page lists arm64, x64, or universal, choose the package that matches the project’s operating system and architecture requirements.
  3. Check whether the system blocked the file. On Windows, check the time and path under “Windows Security” → “Virus & threat protection” → “Protection history.” On macOS, look for a related alert under “System Settings” → “Privacy & Security.” If the package’s source is unknown or the system reports a specific threat, stop running it and get a fresh copy from the project’s trusted release channel. Don’t disable system-wide protection to troubleshoot.
  4. Check whether TUN startup failed. If the logs show that the configuration loaded and the local proxy started listening before a virtual interface, routing, or permissions error appears, the core isn’t missing. If you can open the client, turn off its TUN option and try a regular listener first. If you’re using a local config, set enable to false in the existing tun section of a test copy; don’t add a second section with the same name. If startup works with TUN disabled, check the client’s instructions for its specific service or permission requirements.

Still Crashing with a Minimal Config? Reset Client State, Then Restore Settings One at a Time

If a standalone core of the same version starts with a minimal config but the desktop client still exits as soon as you open it, check the client’s own state: it may be restoring the last config, enabling TUN automatically, or using a stale core path after an upgrade. Quit the app normally and make sure no background process is left running, then find the data directory using the client’s documentation. If the project supports rebuilding user data, back it up first, then temporarily rename the old directory so the app can create a fresh one. Don’t delete the old directory or mix old and new data all at once.

  1. Open the interface with a clean state and load only the minimal config. Quit and open it again to confirm it doesn’t crash when restoring the previous state.
  2. Restore the subscription and confirm the client starts, then restore overrides and rules one at a time. Restart after each change; restore the system proxy or TUN last. If only the minimal direct-connection config works, you’ve isolated part of the problem—it doesn’t prove that the subscription nodes are working.
  3. If it still won’t start, note your operating system, client and core versions, recent changes, and the log lines before and after the first error. Before sharing logs, redact subscription URLs, tokens, node credentials, and local usernames. The final exit message alone is usually not enough to identify the cause.