Clash Crashes on Startup: Read Logs, Fix Port Conflicts, and Roll Back Configurations

First, determine whether the window closed or the core failed to start

Check the system tray or menu bar first, then look at the process list. If the tray icon remains after the window closes, the client may simply be set to minimize to the tray—not crashing. If the window opens but reports a connection failure or unavailable proxy, the core may not have started. The core reads the configuration, matches rules, and forwards connections; the graphical interface is just how you control it.

Note what you did immediately before the problem started. If it began after updating a subscription, check the configuration first. If it started after enabling TUN, check permissions and the virtual network adapter. If the client updated and the window no longer opens, check the application crash report and installer architecture. Don’t update the app, change subscriptions, and modify ports all at once—you won’t know which step made a difference.

Read the logs: keep the context around the first failure

If the interface opens, start with the core logs

Open the client’s Logs page, or look in Settings for options such as Open Config Directory or Open Log Directory. Menu names vary between clients, so don’t assume another client’s folder path applies here. Focus on entries around the latest startup and save roughly 20 lines before and after the error. Repeated “retrying connection” messages at the end are usually just a consequence.

Tell application logs apart from core logs. Application logs record window, update, and service activity; core logs record configuration parsing, port binding, rule loading, and connection handling. If the interface says it can’t connect to the control port, check earlier entries to see whether the core already exited due to a configuration error. Don’t assume the control port is occupied.

If the window won’t open, check system logs

• Windows: Press Win + R, run eventvwr.msc, then open Windows Logs → Application and look for errors at the time of the crash. You can also run perfmon /rel to open Reliability Monitor and view the app’s failure history.
• macOS: Open the Console app and check Crash Reports. Find the report matching the process name and time. Look at the exception type, termination reason, and crashed thread—not just the report title.
• Linux: Launch the actual client executable from a terminal and read its standard error output. If it runs as a user service, use journalctl --user -b to inspect user service logs from the current boot.

Start with keywords to narrow things down. yaml, unmarshal, and parse often point to configuration parsing; address already in use suggests an address or port conflict; permission denied and operation not permitted indicate a permissions issue. Not every error in the logs means the app crashed—for example, a failed download of one rule source may not prevent startup. Check what happens next.

Check the configuration: validate YAML, then verify core support

Start with the lines you changed most recently. YAML uses indentation to express structure, so use spaces and never mix in tabs. Common mistakes include a missing space after a colon, a missing hyphen before a list item, unclosed quotes, or placing rules under dns. The reported line may only be where the parser finally detected the problem, so check the preceding section too.

Confirm which core is running. Clash, Clash Meta, and mihomo don’t support exactly the same configuration options, and the name of the graphical client doesn’t tell you which core it uses. Check About or the startup logs and note both the client and core versions. Don’t assume a field is supported based only on the installer’s name.

Test a copy of the configuration with the same core

Copy the file you want to check to recovery.yaml and work on the copy. The commands below are for mihomo: use -v to check the version, then -t to test the configuration. Use the same core the client actually runs—don’t download a different version just for the test.

# Windows PowerShell: run from the directory containing the core and test file
.\mihomo.exe -v
.\mihomo.exe -t -d . -f .\recovery.yaml

# macOS / Linux: run from the relevant directory
./mihomo -v
./mihomo -t -d . -f ./recovery.yaml

Use -f to specify the configuration file and -d to specify the working directory. Here, . means the current directory. If the original configuration references relative-path rule files, copy those files into the test directory too. Missing local resources can also cause the test to fail, so don’t automatically assume it’s a YAML syntax error.

Use a minimal configuration to isolate subscription and override issues

If you can’t tell which section is causing the problem, temporarily use the mihomo configuration below in a copy. It disables TUN and built-in DNS, exposes a local mixed proxy port, and connects directly to the destination. This is only for checking whether the core starts; it doesn’t provide a remote proxy and isn’t a replacement for a full subscription configuration.

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

tun:
  enable: false

dns:
  enable: false

rules:
  - MATCH,DIRECT

If the minimal configuration starts, restore sections one at a time in this order: subscription base → custom rules → DNS → TUN. Restart after each change. If the problem returns only after an automatic subscription refresh, check the subscription format and the client’s override behavior. Many clients regenerate their runtime configuration, so manual edits to generated files may not survive the next startup.

Troubleshoot port conflicts: identify the process before changing ports

Use the port shown in the logs. 7890 is commonly used for a combined HTTP and SOCKS proxy, while 9090 is often used for the control interface—but both can be changed. Also distinguish a failure to listen from a failed connection: an error near bind points more directly to a local listening issue. A timeout connecting to a remote node isn’t a local port conflict.

Windows: find the PID of the listening process

Open PowerShell and run the command below. A PID (process ID) lets you identify which program owns the listening port. If the command returns no output, it means no matching TCP listeners were found at the time of the query—not that there couldn’t have been a conflict during startup.

Get-NetTCPConnection -State Listen -LocalPort 7890,9090 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress,LocalPort,OwningProcess

# List the names of listening processes
Get-NetTCPConnection -State Listen -LocalPort 7890,9090 -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty OwningProcess -Unique |
  ForEach-Object { Get-Process -Id $_ -ErrorAction SilentlyContinue }

macOS / Linux: identify the process listening on a TCP port

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

Quit the old client normally, then check for any leftover core process or background service. Don’t force-quit an unfamiliar process just because a port is occupied, and never stop a system service. If you decide to change the mixed proxy port to 7895, first confirm that it’s available, then update any manual proxy settings in your browser, terminal environment variables, and other clients.

Handle the control port separately. If you change external-controller, the graphical interface must connect to the new address too. Some clients manage this field themselves, so a manual override can disconnect the interface. If the logs point to DNS port 53, separately check UDP/TCP listeners and system resolver services; the TCP checks above won’t catch every DNS conflict.

Check permissions and service mode: test with TUN disabled first

Disable TUN and start the standard proxy first. TUN routes traffic through a virtual network adapter and typically involves system routes, network interfaces, and elevated permissions. If the client starts with TUN disabled, you’ve narrowed the issue to the virtual adapter, permissions, service, or related configuration—there’s no need to keep switching subscriptions.

1. Check the background service status. In the client settings, look for Service Mode or the corresponding service management option. On Windows, run services.msc and verify the exact service name shown by the client, its status, and the executable path. Don’t guess based on a similar name.
2. Check for path changes after an upgrade. Moving a portable install to another folder, or leaving an old service pointing to a deleted file, can prevent the service from starting. Quit the client first, then use its built-in service repair option or reinstall the service through the client.
3. Check write access to the configuration directory. Try creating a plain text file in the backup directory. If the app’s settings directory is read-only, owned by another user, or blocked by security software, use the logs to identify and fix the specific access issue.
4. Re-enable TUN only after everything else works. Once the standard proxy is stable, enable TUN on its own and check the logs. Avoid running multiple proxies or VPNs that manage system routes at the same time, as their virtual adapters and routing rules may conflict.

Don’t treat “always run as administrator” as a universal fix. Temporarily elevating permissions can help confirm whether the issue is permission-related, but for a lasting fix, follow the client’s service installation process. Configure macOS background helpers and Linux service permissions according to the client’s instructions. Don’t grant unrestricted write access to the entire application directory.

Safe rollback: restore the last working configuration without wiping the directory

Preserve the failed setup first, then return to the last known-good state. Deleting the entire configuration directory can also erase subscription sources, rule overrides, and evidence of the problem. Even if you decide to start over, rename the directory after backing it up instead of deleting it right away.

1. Quit the client completely. After closing the window, check the tray, menu bar, and related processes. If a background service still manages the core, stop the service or core normally through the client first.
2. Make a backup copy. Copy the actual configuration directory to a dated folder, such as clash-backup-2026-09-30, and save the failure logs separately.
3. Restore only what’s related to the failure. If the problem started after changing rules, roll back the rule overrides first. If it began after updating a subscription, switch back to the working configuration. Don’t replace all app settings as a first step.
4. Pause automatic updates temporarily. If the client supports it, pause scheduled refreshes for the affected subscription so restored content isn’t immediately overwritten. Resume updates after the issue is fixed.
5. Verify three things. Confirm that the interface stays open, the logs no longer show repeated restarts, and the expected port is listening. Then test actual proxy access using the full subscription.

If you suspect the app settings themselves are corrupted, back up the configuration directory, rename it, and let the client create a new one. Data directory locations vary by client: some portable versions store data next to the program, while others use the user data directory. Check the actual path in the logs first. When setting things up again, don’t immediately restore all the old settings or you may bring the problem back.

If the issue appeared right after an upgrade, note the old and new client and core versions. Then consider rolling back to a known-good version from the project’s official release channel. Newer versions may write data in a format older versions can’t use, so keep backups from both before and after the upgrade. Don’t let an older version repeatedly rewrite your only copy of the data directory.

Still crashing? Prepare a reproducible troubleshooting report

Gather the details before reporting the issue. “It disappears as soon as I open it” doesn’t distinguish a graphical interface crash from a core exit or background service failure. For system-level errors, see Troubleshooting. If you’re unsure where to import a configuration, see the User Guide.

• Environment: Operating system version, CPU architecture, full client version, full core version, and whether it’s an installed or portable build.
• Steps to reproduce: How long it takes to exit after launch, and whether the issue occurs only after importing a particular subscription, enabling TUN, or switching service modes.
• Test results: Whether the minimal configuration starts, whether the config test passes, and which process is listening on port 7890 or the port you’re using.
• Log excerpt: When the failure occurred, the first key error, and the surrounding context. If the window crashed, include the faulting module or exception type from the system report.

Work through the checks in this order: logs → configuration → ports → permissions → rollback. Change one thing at a time. This makes it easier to narrow down the crash and preserves a clear recovery path, without introducing new configuration differences while trying to fix startup.