Clash
Troubleshooting Manual

Build a repeatable troubleshooting baseline

The first step in troubleshooting is not changing the configuration; it is defining the fault boundary. Record when the issue occurred, the network type, client name, proxy mode, selected node, target website, and the exact error. On desktop, also note whether the system proxy and TUN are enabled. On mobile, record whether the VPN icon appears and whether the system restricts background activity. If the only note is “it does not work,” it becomes difficult to tell which step fixed the problem or to distinguish a temporary network fluctuation from a stable configuration error.

Break the network path into six segments

A connection usually passes through the application, the operating system proxy or virtual network adapter, the Clash listening port, rules and proxy groups, the remote node, and the target service. Failure at any point may appear to the browser as nothing more than a connection timeout. Check from near to far: confirm that the client process is running, the port is listening, the configuration loaded successfully, the proxy group selected a usable node, the node can establish a connection, and the target address accepts the current exit. Do not change the client, subscription, and DNS at the same time; changing multiple variables destroys the basis for comparison.

First disable the system proxy and TUN, then use a browser to open a site that normally works. If direct access also fails, troubleshoot Wi-Fi, Ethernet, the gateway, a captive portal, or system DNS before changing Clash. Once direct access works, start the client without taking over system traffic and check whether the logs show a completed configuration load. Finally enable the system proxy or TUN and test both domain names and raw IP requests. If domains fail while IPs work, DNS is the likely cause; if both fail, continue with the port, node, and route checks.

Collect port and log evidence

Common configurations expose mixed, HTTP, or SOCKS listening ports. Use the values shown by the current configuration and client interface; do not rely on numbers from online examples. On Windows, check listening status in PowerShell; on macOS and Linux, use lsof. No output means the core did not listen successfully, the configuration was not loaded, or another program already occupies the port.

# Windows PowerShell: replace 7890 with the port shown in the interface
Get-NetTCPConnection -LocalPort 7890 -State Listen

# macOS / Linux
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Test through the local HTTP proxy
curl -I --proxy http://127.0.0.1:7890 https://example.com

Start with the info log level. It shows configuration loading, rule matches, DNS queries, and connection errors without producing output as quickly as debug. Raise the level temporarily when tracing a single request, then restore it after reproducing the issue. Save the dozen or so lines before and after the error rather than only the final message; a DNS resolution failure, empty proxy group, or incompatible configuration field may appear before “connection timed out.”

After establishing the baseline, you should be able to answer three questions: Did the client start successfully? Can the local proxy complete a request on its own? Does the problem affect only one node or one type of domain? If not, continue collecting logs instead of jumping to advanced parameters. A stable evidence chain is faster than repeatedly clicking “Update” or “Repair,” and it makes the same issue easier to reproduce across clients.

No internet access after enabling Clash

This symptom usually appears when enabling the system proxy or TUN cuts off browsers, messaging apps, and app stores at once, while disabling takeover restores the network. Do not assume the node is dead. System traffic may already be reaching the local proxy, but the core may have no usable exit, the listening port may not match, or rules may send traffic to an empty proxy group. First prove that the local proxy path works, then check system takeover.

Verify the client’s internal state first

Check whether the configuration page shows the current configuration as loaded, whether the proxy groups contain nodes, and whether the active policy has actually selected one. A subscription update can rename proxy groups, leaving an old selection pointing nowhere; the interface may still appear to be in rule mode while the active group has no valid target. Manually switch to another node and run a latency test as an initial screen, but do not treat a successful latency test as proof that websites will work—the test address, protocol, and real request path may differ.

Next disable the system proxy while leaving the client running, then use curl with the local proxy specified explicitly. If the command succeeds, the core, configuration, and node are broadly working and the fault is on the system or application side. If it returns connection refused, compare the interface port with mixed-port and port in the configuration. If it times out, continue checking the node. For proxy connect aborted or configuration errors, return to the startup logs.

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

# Verify the local proxy independently of system proxy settings
curl -v --proxy http://127.0.0.1:7890 https://example.com

Check for port conflicts and the loopback address

When two proxy clients run on the same device, the core started later may fail to bind its port. Typical logs contain address already in use, bind failed, or listen error. Exit the other client and restart; if both must run, assign different ports to each instance. Do not casually change the listening address to a LAN address. For local use, keep loopback listening enabled; only enable allow-lan when you explicitly need to provide a proxy to LAN devices, and check the firewall and trusted network boundary at the same time.

If an explicitly proxied request succeeds but every application is still offline, turn the system proxy off and on again so the client rewrites the operating system settings. Confirm that the proxy server points to 127.0.0.1 and that the port matches the client. PAC files, other VPNs, browser extensions, and enterprise network tools can leave multiple settings competing with one another. A browser with its own proxy may also bypass system settings. Temporarily restore the browser’s default network settings and test with only one takeover method.

Additional checks for TUN mode

TUN captures more traffic than the system proxy, so a failure in permissions, routing, or DNS has a wider impact. On Windows, check service permissions and the virtual adapter; on macOS, confirm that the system extension or VPN configuration is authorized; on Linux, verify that the process can create a TUN device and modify routes. Do not enable two VPNs that both create a default route. If disabling TUN and using the system proxy restores connectivity, the node and configuration may be fine; focus on the virtual adapter, routing table, and DNS interception.

Also rule out a bad rule match. Temporarily switch to global mode for one short test only: if global mode works but rule mode does not, the request is being sent to the wrong policy or DIRECT. Check the matched rule in the connection log, confirm the final policy for MATCH, and verify that the rule set and proxy group loaded successfully. Restore rule mode after testing; do not hide rule errors behind a permanent global proxy.

Keep the repair order explicit: confirm the basic network works, confirm the client loaded the configuration, confirm the local port is listening, confirm an explicitly proxied request succeeds, and only then restore the system proxy or TUN. Move to the next step only after the current one passes. If you need another client, check the platform and architecture on the download page; when migrating, export the subscription URL and custom rules instead of copying an unknown configuration directory wholesale.

Node timeouts, handshake failures, and reset connections

A timeout in the node list only means that the test request did not finish within the allowed time; it does not prove that the local client is damaged. Possible causes include an unreachable node server, a blocked port, a hostname resolving to the wrong address, incorrect system time, mismatched protocol parameters, or a test URL that is unavailable on the current network. Compare several nodes first: if only one fails, treat it primarily as a node-side issue; if every node in the same subscription fails, inspect the subscription, local network, and protocol support.

Distinguish TCP, TLS, and application-layer failures

In logs, i/o timeout usually means a connection or read/write exceeded its time limit; connection refused means the remote address is reachable but no service is listening on the port; connection reset by peer means the remote side or an intermediary reset an established connection; TLS handshake timeout points to the handshake stage; certificate or server name errors often involve system time, SNI, certificate names, or subscription parameters. Do not reduce all of these to “the node is dead”; each stage calls for different action.

If the node address is a hostname, resolve it with system tools first and confirm that it returns reasonable A or AAAA records. Frequently changing results are not necessarily abnormal, but no result, a reserved address, or an IPv6 address unreachable on the current network points to DNS. Then test TCP reachability to the target port. That test shows only whether the port accepts a connection, not whether protocol authentication works, so if the port is reachable but the client handshake fails, recheck the node parameters.

# Windows PowerShell
Resolve-DnsName node.example.net
Test-NetConnection node.example.net -Port 443

# macOS / Linux
dig node.example.net A
dig node.example.net AAAA
nc -vz node.example.net 443

Check time, protocol, and core support

TLS depends on an accurate system clock. If the device time is far off, certificates may appear not yet valid or already expired. Enable automatic time synchronization and reconnect. Then check whether the protocol type in the subscription is supported by the current core. Older or unmaintained software may not recognize newer fields, resulting in configuration load failures, ignored nodes, or missing handshake parameters. In such cases, prefer maintained clients such as Clash Plus, Clash Verge Rev, FlClash, or a client compatible with mihomo; see the download page for platform-specific options.

Do not manually change the password, UUID, port, transport, TLS switch, server name, or network type generated by the subscription. A single character difference can still allow TCP to connect while making authentication fail every time. If the subscription service provides node details on its website, compare the parsed client fields one by one. Change the subscription format or contact the provider only after confirming that a subscription converter dropped fields.

If the same group of nodes times out on home broadband but works through a mobile hotspot, the issue is more likely in the access network, router DNS, IPv6 path, or port policy. The reverse comparison is useful too: hotspot failure with fixed-line success may indicate mobile IPv6, NAT, or power-saving restrictions. Do not run large numbers of latency tests back to back; high concurrency can trigger remote limits and make logs unreadable. Choose two nodes and reproduce a real webpage request with each.

Separate test addresses from real-world access

Latency tests usually request a fixed URL. If that address is unreachable, the node may be marked as timed out while other sites continue to work. Try the real target in a browser first, then change the test URL. Use a stable HTTPS site with a small response body; avoid pages requiring login or complicated redirects. Set a sensible interval for URL Test groups: intervals that are too short consume more node capacity and battery, while intervals that are too long delay detection of exit changes.

The final diagnosis should come from cross-checking: compare different nodes, networks, and target addresses in at least two sets. Remove a single failing node from the active policy; troubleshoot the network path when all nodes fail on only one network; address client compatibility when every network fails and the logs show unsupported fields. This avoids reinstalling local software during a remote outage and prevents a local DNS problem from being misreported as a failed subscription.

Subscription import, updates, and configuration parsing failures

Subscription problems generally fall into four categories: the link cannot be requested, the server returns a login or error page, the response is not a configuration format supported by the client, or the configuration downloads successfully but fails to parse. An interface message such as “Update failed” often omits the real cause, so inspect the logs or response in a browser. Never publish a complete subscription URL; it may contain access parameters that identify the account. Mask the path and query parameters in troubleshooting screenshots.

Confirm that the link itself is reachable

First check whether spaces, line breaks, or Chinese punctuation were introduced during copying. Some chat apps truncate long links or include the final character in text formatting. Paste the link into a plain-text editor and confirm that it is continuous from the protocol prefix to the end. If the browser redirects to a login page, plan prompt, CAPTCHA, or HTML error page, the client cannot parse it as YAML. Generate a new link from the subscription service instead of editing the client configuration.

If the browser downloads a file, inspect its opening content. Common top-level fields in Clash YAML include proxies, proxy-groups, and rules; some links return encoded text or a format intended for another client, so choose Clash, Meta, or mihomo-compatible output on the server. Do not judge by the file extension alone—the server may return a configuration from a URL with no extension. After downloading, view it in a text editor, but do not let the editor automatically change indentation or tabs.

proxies:
  - name: "Example Node"
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - "Example Node"

rules:
  - MATCH,PROXY

The example above illustrates YAML hierarchy only. Indent list items with spaces, never tabs; pair quotation marks; and keep indentation consistent at the same level. If the parser reports a line and column, inspect upward from that line because the actual indentation error may be on the previous line. duplicate key means a mapping contains the same field more than once; cannot unmarshal usually means the field type is wrong, such as an array written as a string.

Distinguish remote updates from local overrides

Many graphical clients allow overrides, scripts, or merged configurations on top of a subscription. If the remote source is valid but the application fails after applying an override, the problem is in the local processing layer. Temporarily disable overrides and reload; if the client recovers, enable custom DNS, rules, and proxy groups one section at a time. Do not edit cached subscription files directly: the next update will overwrite them and make the issue difficult to reproduce. Keep long-term customizations in the client’s documented override mechanism.

If a subscription update succeeds but no nodes appear, first check whether the response contains proxies, then confirm that the client selected the new configuration. Some clients download successfully but keep the old configuration active until you switch manually; others reject the entire configuration because some fields are incompatible. An updated timestamp in the configuration list proves only that a request occurred, not that the core applied it. The update path is complete only when the core log reports a successful load and the proxy groups list nodes.

Handle network access, certificates, and update frequency

The subscription domain may itself require a proxy, while the client needs the subscription to obtain nodes at startup, creating a circular dependency. Keep a recently working local configuration, start it to establish connectivity, and update the subscription afterward. Do not delete the only working configuration. For certificate errors, correct the clock and check the system certificate environment first; on managed enterprise networks, follow the network’s certificate and access policies.

Repeatedly clicking Update will not fix server-side rate limiting. Wait and try again after HTTP 429; 401 or 403 usually indicate an expired link, account status, or access parameters; 404 means the path does not exist; 5xx points more strongly to a server failure. If the client shows only a short error, use developer logs or a command-line request to inspect the status code, while still hiding the subscription URL in the output.

A stable fix should pass these checks: the subscription returns the correct format, no problematic override is enabled, the logs show a successful configuration load, proxy groups contain nodes, and the same configuration returns after a restart. Review the basic import steps in the Quick Start; to understand compatibility boundaries across cores, read Clash Original, Meta, and mihomo Core Differences.

Connected, but webpages are slow, downloads crawl, or video buffers

Speed issues cannot be judged by node latency alone. Latency describes the round-trip time for a small request; download speed also depends on remote bandwidth, route congestion, packet loss, protocol overhead, target-side throttling, and local device performance. A low-latency node may have very little bandwidth, while a slightly higher-latency node may handle large files better. First identify what is slow: the initial domain lookup, connection setup, sustained download, or only video and specific websites.

Create a direct-versus-proxy comparison

On the same device and network, test direct access and proxy access at roughly the same time. Do not compare different devices or mix Wi-Fi and Ethernet results. Include a small webpage and a sustained download, and record the stable period rather than a momentary peak. If direct access is equally slow, address wireless signal, router load, the carrier route, or the target service; if only the proxy is slow, compare nodes and protocols.

Pause background sync, system updates, and cloud uploads. When upload bandwidth is saturated, acknowledgements cannot return promptly, slowing downloads and webpages together. Test near the access point on Wi-Fi to separate 2.4 GHz interference from proxy issues. If Ethernet works while Wi-Fi is slow, do not change Clash. On mobile hotspots, watch for signal changes and plan-level throttling; a short speed test does not represent sustained transfer quality.

Check DNS first-byte time and connection reuse

A long blank period after clicking, followed by normal loading speed, often indicates slow DNS or an initial handshake. If the logs show unusually long name resolution, address the DNS issues in the DNS chapter first. If the same domain repeatedly creates many new connections, check whether browser extensions, security software, or a network intermediary is breaking connection reuse. Concurrency and connection pools are managed by the core; avoid applying unverified “optimization” parameters just to chase speed.

Automatic proxy groups can also produce misleading results. URL Test chooses a node using only its specified test address, while the actual route to a video site may be completely different. For sustained transfers, manually comparing two or three nodes is more reliable. Fallback switches when the current node is unavailable, while Load Balance changes the exit for different connections; sites with sensitive login sessions may request verification again when the exit changes. During speed troubleshooting, use a fixed node to reduce variables from automatic switching.

Identify MTU, IPv6, and TUN performance issues

In TUN mode, small webpages may open while large files stall or some images never finish loading, possibly because of MTU and path fragmentation. Do not blindly set an extremely small MTU. Compare the system proxy with TUN: if the system proxy works but TUN does not, inspect the virtual adapter defaults, layered VPNs, and router path. Some networks have incomplete IPv6 reachability, causing a delay while IPv6 is tried, fails, and falls back to IPv4. Logs and DNS results can confirm whether this is happening.

# Measure request-phase timing, focusing on name lookup, connect, and start transfer
curl -o /dev/null -s \
  -w "dns=%{time_namelookup}\nconnect=%{time_connect}\ntls=%{time_appconnect}\nfirst_byte=%{time_starttransfer}\ntotal=%{time_total}\n" \
  --proxy http://127.0.0.1:7890 \
  https://example.com

Include the client’s resource usage in your observations. Large rule sets, verbose logs, frequent health checks, and complex scripts increase CPU and memory load, especially on low-power devices. First disable debug logging, lengthen overly frequent health-check intervals, and turn off unnecessary overrides, then compare performance. Routers and older phones running full TUN may also be limited by single-core performance. Changing nodes cannot fix a local processing bottleneck.

The final record should include direct results, proxy results, node, takeover mode, DNS-phase timing, and test window. If the issue is specific to the difference between TUN and the system proxy, continue with TUN Mode vs. System Proxy: How They Work. With this data, you can decide whether to change nodes, correct rules, adjust DNS, or repair the local wireless network.

DNS resolution failures, poisoning, leaks, and query loops

DNS trouble is more than a “server not found” message. Common signs include intermittent domain failures, different results across applications, system resolution continuing after the proxy is enabled, fake-IP addresses that applications cannot handle, broken internal domains, and queries looping between the local proxy and the system resolver. Draw the resolution path first: who receives the application’s query, whether Clash listens for DNS, whether the upstream is reached directly or through the proxy, and which component ultimately returns the result.

First determine whether the problem is resolution or connectivity

Use nslookup, dig, or the system resolver command to see whether the domain returns an address, then check the logs to confirm whether Clash received the query. If resolution succeeds but the connection times out, the node or target path may be at fault; if raw IP requests work while domains fail, DNS is more likely. Browsers may use their own secure DNS and produce different results from system commands. Temporarily disable custom browser DNS during troubleshooting so everything follows the system or Clash path.

# Query the resolution path currently used by the system
nslookup example.com

# macOS / Linux: view A and AAAA records
dig example.com A
dig example.com AAAA

# When specifying the local DNS listening port
dig @127.0.0.1 -p 1053 example.com

If the local DNS port is not listening, check that DNS is enabled, that the port is free, and that the core has permission to bind it. Port 53 usually requires elevated privileges and often conflicts with system services; desktop clients commonly use internal forwarding or a high port instead, so do not force 53 just because an example does. Handle bind failed, address already in use, and permission denied according to whether the cause is port ownership or permissions.

Understand the boundary between fake-ip and redir-host

fake-ip returns reserved addresses to applications while the core maintains the domain mapping, making domain-based rules easier to apply and reducing some resolution bypasses. Certain LAN discovery features, legacy programs, games, or services that require the real address may be incompatible and need to be added to fake-ip-filter. Do not put every domain in the filter list, or fake-ip loses its main purpose. Use logs to identify the exact domains and add only required internal suffixes, discovery domains, or confirmed exceptions.

dns:
  enable: true
  enhanced-mode: fake-ip
  listen: 127.0.0.1:1053
  nameserver:
    - https://1.1.1.1/dns-query
  fallback:
    - https://8.8.8.8/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

The upstreams in examples are for syntax only; choose actual servers based on reachability and privacy requirements. Encrypted DNS addresses also need to be resolved, relying on bootstrap or default-nameserver. If all bootstrap resolution points to a server reachable only through the proxy, while the proxy node hostname itself depends on that resolver, startup enters a loop. A sound path lets the node hostname and encrypted DNS hostname resolve through a resolver reachable during startup, after which Clash takes over subsequent queries.

Handle DNS leaks and multiple resolvers

A DNS leak is primarily about whether application queries bypass the intended path, not how many servers a test page displays. The system proxy generally captures connections from proxy-aware applications but does not automatically capture all system DNS; TUN with DNS interception covers more traffic but depends more heavily on correct routing. Check browser secure DNS, operating-system encrypted DNS, other VPNs, and security software to ensure that multiple components are not competing for queries. For a complete procedure, see Clash DNS Leak Detection and Prevention Configuration.

When internal domains fail to resolve, do not immediately delete all Clash DNS settings. Private domains on corporate or home networks are often resolvable only by the LAN DNS and can be sent there through nameserver-policy or a dedicated domain rule. Once the device leaves that network, the internal resolver is unreachable, so configure a fallback. Short hostnames may also depend on a DHCP-provided search suffix; if the fully qualified domain works but the short name fails, check the system search domain rather than the proxy node.

After fixing the issue, clear the necessary system and browser DNS caches, restart the client once, and test the system command, browser, and actual application separately. The logs should show queries entering the expected listener, reachable upstream requests, and returned addresses consistent with connection rules. If the issue returns after a restart, check whether another network tool rewrites DNS during login. DNS troubleshooting ends when the resolution path is clear, applications behave consistently, and internal and public domains follow their intended policies—not when a test page displays a particular name.

System proxy enabled, but the application is unaffected

The system proxy does not force all traffic into Clash. It merely publishes an HTTP, HTTPS, or SOCKS proxy address to applications that support the mechanism. Browsers usually read it, while some games, command-line tools, store apps, and software with its own network stack may ignore it. Seeing “system proxy enabled” in the client proves only that the write operation ran, not that the target application adopted it. Check the operating system settings, application settings, and local proxy logs together.

Confirm the address and port recorded by the system

Open the system network settings and confirm that the proxy server is a loopback address and that its port matches the client’s current listener. Changing configurations, switching cores, or installing multiple clients can leave an old port behind. On Windows, distinguish the system proxy, WinHTTP proxy, and application-specific settings; on macOS, proxy settings are stored per network service, so Wi-Fi and Ethernet may differ; on Linux, a desktop-wide proxy does not automatically affect every terminal program.

# Windows: view WinHTTP proxy status
netsh winhttp show proxy

# macOS: view the Web proxy for the Wi-Fi network service
networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi

# Linux / general terminal: check environment variables
env | grep -i proxy

Command-line programs commonly read HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, but support depends on the program. Environment variables affect only processes that inherit them at startup; already-open terminals and editors may retain old values. Reopen the terminal after setting them, then clear them after testing so commands do not continue pointing to a nonexistent local port after the client exits.

# Temporarily use an HTTP proxy in the current terminal
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# Use SOCKS5 and let the proxy resolve the hostname
export ALL_PROXY=socks5h://127.0.0.1:7890

# Clear the settings after testing
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Handle bypass lists, PAC, and application-specific proxies

The system bypass list sends matching addresses directly. If it contains an overly broad wildcard, the target site may never reach Clash. PAC scripts also return DIRECT or PROXY for each URL; cached scripts, stale addresses, or rule errors can make only some sites bypass the proxy. Disable PAC first and verify with a fixed system proxy. If the fixed proxy works, inspect the PAC content and download status separately.

Browser extensions, developer tools, containers, and IDEs may have their own proxy settings. When those settings take priority over the system proxy, switching the client will not affect them. Check the target application’s network options, restore “use system settings,” or enter the current local port directly. For programs that do not support system proxies at all, TUN may be more suitable, but first confirm that permissions, routes, and DNS work as described above.

Distinguish rule-based direct access from no takeover

If an application request appears in the Clash connection log but the exit is DIRECT, the system proxy is working and the rules chose a direct connection. Inspect the matched rule and proxy group instead of changing system settings again. If no request appears in the log at all, the application is bypassing the proxy or was not captured. Temporarily switching to global mode can verify the rule branch, but restore it afterward and correct the specific domain or rule set.

LAN addresses should usually remain direct. Do not delete local-network bypasses just to make every request appear in the logs; printers, NAS devices, router admin pages, and device discovery may break. “Bypass local addresses” in the system proxy and DIRECT rules for private ranges in Clash can coexist because they operate at different layers. When testing a public destination, use a clearly public domain to avoid interference from LAN exceptions.

For acceptance testing, choose one browser and one command-line tool: the browser should access the internet through the system proxy, and the command-line tool through an explicit proxy; both should appear in the logs. Then close Clash and confirm that the system proxy is cleared and direct access returns. If the system proxy cannot cover the target program, evaluate TUN instead of treating “system proxy enabled” as forced takeover. Continue with the Proxy Mode Comparison for the boundaries of each method.

Client startup failures, crashes, and repeatedly exiting cores

First distinguish a graphical interface exit, a core process exit, and termination by the operating system. If the interface closes but the proxy still works, the core may be running in the background; if the interface is normal but no port is listening, the core may have failed to start; if the entire program disappears, check system crash reports, memory pressure, and security policies. Do not restart repeatedly before saving logs; consecutive launches may overwrite the most valuable first error.

Start with an empty configuration and the latest change

Recall the last action before the crash: updating a subscription, enabling TUN, importing an override, switching cores, upgrading the client, or changing the theme. If the client offers safe mode, disable automatic loading of the last configuration first; otherwise back up the configuration directory, move the latest configuration out, and start a blank environment. If the empty configuration starts, the program itself is broadly healthy; restore subscriptions and overrides one at a time. If it still crashes, inspect runtimes, permissions, installation files, and system logs.

A core exit caused by configuration usually leaves a parse error, unknown field, proxy group referring to a missing node, missing rule-set file, or failed port bind. Act on the first fatal or error entry in the log rather than the later “core exited” message. If the configuration came from a subscription, disable local overrides first; if only one subscription triggers the crash, keep a redacted minimal configuration for diagnosis. Remove node passwords and subscription parameters before sharing logs.

Check ports, file permissions, and disk health

A port conflict can make the core exit immediately after startup. Fully close other proxy programs and check Task Manager or Activity Monitor for an old core that is still running. If the configuration directory is not writable, the client may fail to update its cache, database, or logs; insufficient disk space can also cause writes to fail. Do not run as administrator permanently to bypass every permission issue. Put the configuration directory somewhere the current user can read and write, and let the client’s official mechanism handle the elevation required by TUN.

On Windows, check application errors in Event Viewer and record the faulting module; on macOS, inspect the system-generated crash report; on Linux, start the client from a terminal to reveal missing libraries, permission issues, and graphics-backend errors. When running mihomo on a server, use systemd to inspect recent logs and confirm the exit code and restart count.

# Linux: view service status and recent logs
systemctl status mihomo --no-pager
journalctl -u mihomo -n 120 --no-pager

# Check configuration syntax; adjust the path to the actual installation location
mihomo -t -f /etc/mihomo/config.yaml

Handle upgrades, migration, and compatibility

Do not copy an entire application data directory when migrating between clients. Databases, interface settings, override formats, and core paths differ between clients. A safer approach is to export the subscription URL, custom rules, and required DNS fragments, then rebuild the configuration in the new client. Clash Plus is preferred on desktop; Clash Verge Rev, FlClash, and Clash Nyanpasu are also options. Clash for Windows and ClashX Meta are no longer maintained and should not be the first choice for resolving compatibility with new configurations.

If startup fails after an upgrade, check the release notes for changes to the configuration directory, core interface, or system requirements. This site does not hard-code specific version numbers in the article; currently available packages are provided through the download page. Back up user configurations before reinstalling, then uninstall and install the package for the matching architecture through the normal system process. Do not mix ARM and x64 packages; on macOS, distinguish Apple Silicon from Intel. The wrong package architecture may fail immediately or run through translation with performance and extension-permission issues.

When security software blocks the client, inspect the specific block event and file path instead of guessing and disabling all protection. Managed enterprise devices may prohibit VPN creation, network extensions, or unapproved programs; the device administrator must handle those restrictions. If a file is quarantined, first confirm that the download came from the corresponding client entry provided by this site, then restore or reinstall it according to system policy. Do not obtain missing components from unknown mirror pages.

Crash repair is not accepted merely because “the interface opens.” Confirm that the core keeps running, the local port remains stable, the configuration passes syntax checks, and the system proxy can be toggled normally; then test again after rebooting the system. If an empty configuration is stable but restoring a custom section causes another exit, keep narrowing that section until you find the smallest trigger. This is more conclusive than repeatedly installing multiple clients.

Android and iOS mobile troubleshooting

Mobile clients take over traffic through the system VPN interface, so failures often come from system lifecycle management rather than configuration syntax. Disconnections when the screen turns off, stalls after switching from Wi-Fi to cellular, failures limited to certain apps, and a repeatedly disappearing VPN icon all require checks of background permission, always-on VPN, low-power mode, data saving, and other VPN conflicts. A mobile device generally supports only one VPN tunnel at a time; ad blockers, enterprise VPNs, and Clash clients cannot occupy the same interface simultaneously.

Android: background operation, VPN permission, and per-app routing

The first Android connection shows a VPN authorization dialog. Without authorization, the client can import a configuration but cannot establish the system tunnel. If the connect button immediately returns to a disconnected state, check whether authorization was revoked. Some vendor systems restrict background processes after the screen turns off; add the client to the allowed-background or battery-optimization-exempt list and allow autostart. Settings names vary by device, but the goal is the same: the system must not freeze the client while the tunnel is active.

If only certain applications bypass the proxy, inspect per-app routing or the VPN bypass list. Per-app proxying can include only selected apps or exclude selected apps; choosing the wrong mode can send most applications direct. Before enabling “block connections without VPN,” confirm that the client reliably reconnects at boot and after network changes. Otherwise the device may appear completely offline during a brief client exit. Disable this restriction while troubleshooting, then enable it again once the connection is stable.

If connectivity does not recover after switching from Wi-Fi to cellular, disconnect and reconnect the tunnel and check whether the logs resolve the node hostname and establish a new connection. Mobile networks may prefer IPv6 while the node hostname or DNS path supports only IPv4; private DNS and the client DNS may also operate simultaneously. Temporarily set Android Private DNS to Automatic and retest through the client’s default DNS path. If that works, decide which resolution mechanism to keep.

iOS: VPN profiles, on-demand connections, and network switching

On first activation, iOS asks for permission to add a VPN configuration. If several similar profiles exist in system settings, confirm that the active one corresponds to Clash Plus. Clash Plus is the recommended mobile choice on this site; install it through the App Store and verify the official information at the iOS download entry. If no VPN status appears after connecting, return to the system VPN page to see whether it is still connecting or disconnecting immediately, then return to the client and read the logs.

Low Power Mode and system resource reclamation can affect background maintenance, although a normal Network Extension is managed by the system. If the client is force-quit manually, the tunnel may stop; avoid repeatedly swiping the app away from the multitasking view during troubleshooting. Incorrect on-demand rules can connect on Wi-Fi but disconnect on cellular, or loop after entering a particular network. Disable complex on-demand rules, establish a stable manual connection, then restore network conditions one by one.

Mobile subscription and certificate issues

When copying a subscription link in a mobile browser, it is easy to copy displayed page text instead of the actual URL. Use the service page’s copy button, then check the beginning and end after pasting; do not transcribe it from a screenshot. If subscription updates fail on Wi-Fi but work on cellular, check the Wi-Fi captive portal and DNS; reverse the checks when cellular fails. If system settings block the client from using mobile data, the tunnel interface may still appear while subscription updates and node connections fail.

System time also affects mobile TLS. Enable automatic date and time zone. Public Wi-Fi often requires web authentication, but a VPN that takes over too early may prevent the login page from appearing. Disconnect Clash, complete the network login, confirm that direct webpages work, and then establish the tunnel. After leaving the public network, turning Wi-Fi off and on is usually more effective than changing proxy settings.

Mobile acceptance testing should cover four rounds: connect and browse on Wi-Fi, continue browsing after switching to cellular, recover after locking the screen for several minutes, and reload the subscription after restarting the client. Watch the VPN icon and logs every round. If both Android and iOS fail on the same network and subscription, the node or subscription is more likely at fault; if only one device fails, check its permissions, DNS, and system restrictions. If reinstallation is needed, choose Clash Plus, Clash Meta for Android, FlClash, or Surfboard from the Android download section; on iOS, use the Clash Plus store entry.

After troubleshooting, keep a short record of the operating system, client, takeover mode, failing network, log keywords, changes made, and final result. When the same symptom returns, reuse the verified steps instead of trying every setting again. For the relationships between client projects and core sources, read the Clash Open Source Ecosystem Project Map to distinguish graphical clients, cores, and mobile implementations.