Complete Clash Troubleshooting Guide

01 · Establish reproducible conditions

Troubleshooting baseline: identify the failing layer first

Break the connection path into six stages

A Clash request is not simply a direct connection between the client and a website. The full path includes at least six stages: the application, system proxy or TUN capture, the local listening port, Clash rule matching, the proxy node, and the destination site. A browser failing to open a page only proves that at least one stage failed; it does not prove that the node is down or the subscription is corrupt. Verify the path from the device outward: confirm that ordinary networking works, then check that the Clash process exists, followed by the port, proxy group, rule match, node connection, and destination status. Working outward from the device prevents repeated node switching while missing basic issues such as a local port conflict.

Record the current environment before starting. At minimum, note the operating system, client name, network type, proxy mode, selected proxy group, whether the issue affects one app or every app, and whether networking recovers when Clash is closed. On Windows and macOS desktops, Clash Plus is a practical first choice; see the Download Center for other clients and platform requirements. If the issue occurs on the first connection after installation, complete the basics in the quick setup guide before entering a troubleshooting branch. If it previously worked, also record recent changes such as a system upgrade, subscription update, Wi-Fi change, security software installation, or configuration edit.

Create a minimal test environment

Keep only one browser, one known-good configuration, and one proxy node in the minimal test environment. Quit other proxies, VPNs, network filters, packet-capture tools, and local development proxies to prevent multiple programs from rewriting system proxy settings or claiming the same port. Disable standalone browser proxy extensions and test in a regular window; an extension may bypass system settings or retain an old port. Temporarily switch to Rule mode and select one specific node in the proxy group instead of using auto-select or load balancing. Automatic groups may switch destinations in the background, making test conditions inconsistent and obscuring whether the problem is the node or the policy.

Keep the baseline configuration simple. Reduce commonly used listener settings to a mixed port, LAN access toggle, Rule mode, and a logging level. Back up the original file before editing, then reload it from the client rather than merely saving the text. The snippet below is suitable for local verification. If the client manages these fields through a graphical interface, follow the configuration generated by that interface to avoid the UI and hand-written file overwriting each other.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

mixed-port accepts both HTTP and SOCKS connections, which helps avoid port confusion; allow-lan: false limits testing to the local device; mode: rule preserves the real rule path; and log-level: info is usually enough to observe rule matches and connection errors. Restore LAN sharing, scripts, overrides, and advanced DNS only after troubleshooting. Do not start with extremely verbose logging: repetitive output can bury the first meaningful error and increase storage and battery usage on mobile devices.

Read the first failure in the logs

Read logs in this order: time, destination, rule, policy, node, and error. Clear the log or note the current time, then make one request. If no new entry appears, the problem usually lies between the application and Clash; check the system proxy, browser proxy, or TUN capture. If the log shows the destination and a rule but no outbound connection, inspect the proxy group and node. If a connection was made but ends with a certificate error, reset, refusal, or timeout, check the clock, DNS, network restrictions, and remote status. Do not capture only the last line; the previous line often identifies the rule, proxy group, and actual destination.

Change one variable per round and record the result as “recovered,” “unchanged,” or “symptom changed.” For example, change the node first, then change the mode only after confirming the result. Do not switch nodes, refresh the subscription, change DNS, and reboot the router at once. A changed symptom is useful too: going from no logs at all to a connection timeout indicates that the system proxy path is working again, so the next step is the node or network layer. After one round, move to the section matching the clearest symptom. If several symptoms occur together, address upstream issues first, such as a process that will not start, missing logs, or every node failing.

02 · No pages open

Clash has no internet: separate local networking, traffic capture, and rule egress

Start with an off/on comparison

The first step when there is no internet is not to cycle through nodes. Make two comparisons. Fully quit Clash, confirm that the system proxy is off, and visit a normally reliable site. If it still cannot be reached, the problem is in the underlying network, router, ISP, or system DNS; further Clash changes will not fix it. If connectivity returns immediately after quitting, the fault lies after proxy capture. Restart the client without enabling the system proxy, and check whether it loads the configuration normally, reports parsing errors, and displays proxy groups in its control panel. Once the client itself is healthy, enable the system proxy and make a second request.

“Quit” must end the process, not merely close its window. Some desktop clients remain in the tray and continue applying the system proxy. On Windows, check the notification area and Task Manager; on macOS, check the menu bar and Activity Monitor. If force-quitting restores networking but a normal quit leaves it offline, the client likely failed to restore the system proxy on exit. Turn off the proxy server in system network settings, then restart the client. Do not delete unknown network settings; record their original values first, especially on corporate or development networks that may intentionally use a fixed proxy.

Confirm the local listening port

The address and port used by the system proxy must match what Clash is actually listening on. A common local address is 127.0.0.1, and a mixed port may be 7890, but use the values from the current configuration. If the system still points to an old port, the browser sends requests to a nonexistent service and every page fails immediately. Another process may also occupy the port; client logs often report that the address is already in use or that listening failed. End the process holding it, or change both the Clash listening port and the system proxy port together. Never change only one side.

# Windows: check port 7890
netstat -ano | findstr :7890

# macOS / Linux: check the listening process
lsof -nP -iTCP:7890 -sTCP:LISTEN

No command output means the port is not listening successfully. If the process is not the current Clash client, identify its purpose first. A listening port does not guarantee outbound traffic, so check whether requests reach the log. When the browser makes a request, a completely quiet log usually means the system proxy is inactive or the application bypasses it. If requests appear but all use DIRECT, inspect the mode and rules. If requests enter a proxy group and fail, continue to the node-timeout section.

Narrow the scope by switching modes

Temporarily switch to Global mode and select one specific node for diagnosis. If Global mode works but Rule mode does not, the node and local port are probably healthy; focus on rule order, rule-set downloads, and the final MATCH. Rules are evaluated from top to bottom, and the first match ends evaluation. An overly broad DOMAIN-SUFFIX, an incorrect GEOIP policy, or an early MATCH,DIRECT can send traffic to the wrong strategy. Restore Rule mode after correcting the rules; do not use Global mode long-term to hide a configuration error.

If Global mode also fails, test the same node on another network, such as switching from home Wi-Fi to a phone hotspot. If the hotspot works but the original network does not, the configuration and node are probably fine; inspect the router, firewall, IPv6 path, or restrictions on specific connections. If both networks fail, try a node on a different route. If only one node fails, the issue is limited to that node. If every node fails while direct access works, check whether the subscription is complete, the system clock is accurate, the client core loaded correctly, and security software is blocking the client.

Some applications use UDP, QUIC, or their own network stack, so a working browser does not prove that every app works. Temporarily disable QUIC in the target app or test over TCP, then check whether the node supports UDP. For LAN sharing, make sure the device uses the host machine’s LAN address—not 127.0.0.1—as the proxy address; the latter always means the device itself. Shared access requires allow-lan, an appropriate listening address, and an allowed system firewall port. See Mixed Ports and LAN Sharing for the port relationships.

03 · Nodes show timeouts

Node timeouts: check the test address, handshake stage, and network path

Latency checks are not full speed tests

A client “timeout” usually means that a connection or HTTP request to the test address did not finish within the limit. It does not necessarily mean the node is unusable for every destination. The test passes through the local network, node ingress, node egress, DNS, and the test site; slowness at any stage can trigger a timeout. Test URLs, timeout thresholds, and connection reuse vary by client, so the same node may produce different results in Clash Plus, Clash Verge Rev, and other clients. A latency figure is not a download speed. For the details, read How Node Latency Tests Work.

Choose one node and visit two different destinations: an ordinary web page and a small static resource. If real browsing works but the panel test times out, inspect whether the test URL is reachable from the node’s egress and review the subscription’s health-check settings. If real browsing also fails, identify the failing stage in the log. A connection refusal usually means no service is listening on the destination port or the ingress rejected the connection; a timeout suggests no response from the path; a TLS handshake error calls for checking the system clock, certificate chain, SNI, and intermediate network; and a name-resolution failure belongs in the DNS section.

Compare one node, the proxy group, and the network

A timeout in an auto-select group does not mean every node in the group timed out. Expand the group, select a specific node manually, and run two consecutive tests on the same network. The first may include DNS and handshake costs; the second helps confirm stability. Then repeat with nodes from different regions or using different protocols. If the same batch fails, the subscription provider may be maintaining routes, changing ingress addresses, or supplying mismatched protocol parameters. If every node fails simultaneously, prioritize the local firewall, network restrictions, system clock, and configuration parsing instead of deleting nodes one by one.

Use a phone hotspot as a network comparison. If the hotspot works, the client, configuration, and node can at least establish a connection, so inspect the original Wi-Fi path. Public networks often require web authentication; before enabling the proxy, open a regular HTTP page and complete authentication, then start Clash. Corporate networks may allow only limited outbound ports, while home routers can have IPv6, MTU, or DNS-forwarding issues. Do not dismiss “works on a hotspot” as simple node fluctuation; it clearly ties the failure to the access network, so preserve the evidence.

Check the clock, IPv6, and MTU

TLS connections depend on an accurate system clock. A significant clock error can make certificates appear not yet valid or expired, producing handshake or certificate errors in the log. Enable automatic time synchronization, restart the client, and test again. With IPv6, a domain may prefer an AAAA address even when the node or local network lacks a stable IPv6 route, causing some destinations to wait and fail. Temporarily disable IPv6 in the configuration, reload it, and clear the DNS cache. If the issue disappears, decide whether to keep IPv6 disabled or repair IPv6 support locally and on the node.

A small page may open while large files or some applications stall because of MTU. TUN mode adds encapsulation, and some networks handle fragmentation poorly, causing larger packets to be dropped. Disable TUN temporarily and test with only the system proxy. If the system proxy works but TUN times out, inspect the client’s MTU setting, the virtual network adapter, and other VPN drivers. Do not make large MTU changes by guesswork; lower it gradually and retest the same destination. Once it works, record the effective value and check whether LAN and hotspot networks need different settings.

Health-check parameters can also create false positives. The test address should return a stable, small response without requiring a login. The interval should not be so short that it continuously consumes mobile data, and the timeout should not be shorter than a normal handshake on the current network. If the provider supplies several auto-select groups, verify each group’s node set and test URL separately. Changing health checks improves detection accuracy but cannot repair a genuinely dead node. Make the final judgment using real browsing, the log stage, comparisons across networks, and results from other nodes in the same group.

04 · Configuration will not update

Subscription failures: check the link, response, parsing, and overrides

First distinguish download failures from parsing failures

A subscription update has two separate stages: the client downloads the content over the network, then the core parses it as a configuration. Download failures commonly appear as connection timeouts, unexpected status codes, certificate errors, or an unresolvable subscription domain. Parsing failures usually mean content was received, but its YAML syntax, field types, node parameters, or rule-provider format is invalid. The remedies are completely different. Find the first error in the log and check for an HTTP status, response length, or YAML line number. When the only message is “update failed,” open detailed logs or the configuration manager for the exact cause.

Preserve the complete query string when copying a subscription link. Chat apps may truncate it, escape special characters, or append punctuation. The safest method is to use the provider’s copy button, then paste the link into a plain-text editor: it should start with https:// and contain no spaces or line breaks. If the subscription uses a temporary token, an old link may stop working after a reset. Never paste a subscription link into public logs, screenshots, or online parsers; it usually contains access credentials.

Inspect the network response without exposing the link

Open the subscription link directly in a browser to see whether it downloads text, redirects to a login page, or returns an error page. If the browser also fails, the issue is not client parsing; check the underlying network, DNS, account status, and server restrictions. If the browser downloads it but the client does not, determine whether the client updates subscriptions directly or through the current proxy. Some subscription domains are unreachable on the current network and require an existing configuration first; the reverse can also happen when an incorrect proxy rule sends the request through a dead node. In that case, temporarily disable the proxy and update again.

When verifying from the command line, do not place the complete link in shared terminal history. Use a temporary local environment and inspect only the response headers and first few lines. The expected response is usually a YAML configuration or encoded subscription content, not an HTML login page. A successful status with webpage content still causes parsing to fail. After redirects, verify the final domain’s certificate, the device clock, and whether a network login page intercepted the request.

Locate the YAML line and field type

Parsing errors often include a line number. Check that line and the one above it first, because a missing quote, bad indentation, or a colon without a following space is often detected on the next line. YAML uses spaces for indentation; do not mix in tabs. Quote text values containing colons, hash marks, or special characters. Use true or false for booleans, and use numbers for ports. Proxy-group node names must exactly match the names in the node list; capitalization and spaces both matter.

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "DIRECT"

rules:
  - DOMAIN-SUFFIX,example.com,Node Selection
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

If the original subscription parses successfully but fails after client overrides are applied, temporarily disable scripts, config merges, rule overrides, and custom templates, then import the original subscription again. Clients may implement override order differently, and an old template may reference a deleted proxy group. Re-enable items one at a time, reloading and checking the log after each one. This identifies whether the conflict comes from the upstream subscription or a local override. When sharing configurations across devices, also check paths, external rule files, and platform-specific fields. See Configuration Sync Across Devices for the trade-offs.

Handle an old configuration that remains active after updating

A successful download does not mean the active runtime configuration has changed. Some clients separate “download configuration” from “activate configuration.” After the subscription list shows a new timestamp, select that configuration and reload it. If the UI still shows the old proxy group, check the active configuration name, file path, and update time to avoid refreshing a different entry with the same name. Temporarily give a test group a distinctive name to confirm which file the core loaded, then restore it afterward.

When scheduled subscription updates fail repeatedly, lengthen the update interval and avoid multiple devices making requests at the same time. Mobile operating systems may pause the client in the background, preventing a scheduled task from running on time; that does not mean the link is invalid. The final checks are whether a manual update retrieves valid content, whether the content parses, and whether the active core has loaded the new configuration. If the server returns an authorization or quota error, the provider must resolve it; local client edits cannot bypass server authorization.

05 · Connected but slow

Slow speeds: measure latency, throughput, packet loss, and rule paths separately

Define exactly what “slow” means

Slow performance can mean a slow first render, slow sustained downloads, video buffering, gaming jitter, or intermittent stalls. Each points to different metrics: first render depends more on DNS and handshake latency, sustained downloads depend on bandwidth and congestion, and real-time apps are more sensitive to packet loss and jitter. A millisecond figure in the client cannot capture these differences. Use the same device, network, destination, and approximate time to compare direct access, one fixed node, and another fixed node. An auto-select group changes the egress and is not a reliable baseline.

Before testing, pause system updates, cloud synchronization, video playback, and high-bandwidth tasks on other devices. Browser speed tests can be affected by extensions, cache, and QUIC; use a private window and repeat two or three times. Do not run tests continuously at high frequency, or you may saturate the route and distort later results. Record time to first byte, stable download speed, and any sudden drops to zero. If direct access is also slow, address local Wi-Fi, router load, or the ISP first. If only the proxy is slow, compare nodes, protocols, and rule paths.

Confirm which egress the destination actually uses

In Rule mode, different domains may enter different proxy groups. A proxied page domain does not mean its images, video segments, and APIs use the same egress. Open the connection log, search for the destination domain, and inspect the matched rule and policy. Incorrect rules can send static resources direct, route services that should be direct through a distant node, or send several high-volume domains to a congested route. Rules are evaluated from top to bottom; see Clash Rule-Based Routing in Practice for syntax and ordering.

Temporarily switch to Global mode and pin the same node to verify whether rules cause the difference. If Global mode is clearly faster, do not keep it permanently; compare connection records and identify domains that use different policies in Rule mode. If both modes are slow, rules are not the main cause. Try nodes in the same region. If only one is slow, the route may be congested or its egress quality poor. If every node is slow on the current Wi-Fi but the hotspot works, inspect the local network, MTU, IPv6, and router traffic management.

DNS, connection reuse, and protocol differences

A slow DNS response makes every new domain wait, while an established download connection may remain healthy. Typical signs are a slow first load, faster refreshes, or individual page resources appearing late. Check domain-resolution time in the log and compare Clash DNS with system DNS. Do not run several local DNS tools that forward to one another, or requests may form a long chain or loop. In Fake-IP mode, the app receives a reserved address that Clash maps back to the real domain. A broken mapping cache or an app that bypasses system resolution can also cause intermittent stalls.

Some networks handle UDP poorly, while browsers may prefer QUIC. Temporarily disable QUIC in the browser or make the traffic fall back to TCP. If stability improves, the problem is concentrated on the UDP path. A node labeled as UDP-capable does not guarantee stability across the current access network, router, and egress route. For games and voice apps, watch sustained packet loss rather than chasing the lowest latency. TUN captures more traffic but adds a virtual adapter and extra encapsulation. If the system proxy is faster than TUN, inspect MTU, adapter drivers, and exclusion routes.

Use sensible parameters for auto-select groups

Auto-select generally chooses a node from health-check results, but the test address and real workload follow different paths. The lowest test latency may not deliver the highest throughput. A node suited to browsing may be poor for large downloads or real-time apps. Create separate groups for separate uses: auto-select for everyday browsing, a manually pinned node for downloads or video, and DIRECT for services that should bypass the proxy. Do not put dozens of widely varying nodes into a group that checks constantly; repeated tests consume resources and may switch egress repeatedly.

Speed drops at fixed times are often caused by route congestion or local wireless interference. Retest over Ethernet or close to the router to separate Wi-Fi from the remote path, and compare the same node off-peak. If a large download starts fast and then steadily declines, possible causes include egress throttling, congestion control, or server rate limiting. If speed repeatedly drops to zero and recovers, packet loss, network switching, or connection rebuilding is more likely. Record the time, node, and destination before changing routes; do not rewrite the entire configuration based on one speed test.

06 · Domain resolution failures

DNS issues: check the resolution entry point, mode, cache, and fallback chain

Recognize DNS failure patterns

DNS problems often appear as a domain that will not open, a known address that responds directly, some domains working while others fail, or old results persisting after a network change. Logs may show no such host, resolution timeouts, unreachable upstreams, or missing Fake-IP mappings. A certificate-name mismatch can also result from incorrect resolution, but first rule out the system clock and captive-portal page. Pick one failing domain and record both the system result and the resolution process in the Clash log. Do not test many unrelated domains at once.

The DNS path may pass through browser Secure DNS, the system resolver, a local filter, Clash DNS, the router, and an upstream server. The longer the chain, the more likely it is to contain loops, inconsistent caches, or routing mistakes. Temporarily disable browser-specific Secure DNS and other local DNS tools so requests use only the system and Clash. If the browser recovers while other apps were already fine, the browser’s independent resolver is the likely cause. If every app fails, inspect the Clash DNS listener, TUN interception, and upstream reachability.

Understand redir-host and Fake-IP

redir-host normally returns the real resolved address, then lets rules handle the connection. Fake-IP first returns a mapped address from a reserved range, allowing Clash to retain the domain name and apply rules earlier. Fake-IP is not a remote node address and should not be added to hosts manually. Some LAN devices, games, enterprise apps, or software with unusual DNS behavior are less compatible with Fake-IP; add only those domains to the filter so they receive real addresses. Target confirmed domains precisely; do not exclude most requests with an overly broad wildcard.

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

This example illustrates field relationships and does not mean every network should use the same upstream. ipv6: false is useful as a diagnostic switch; re-enable it after confirming that the IPv6 path is stable. An upstream DNS server must be reachable on the current network. If the upstream itself requires the proxy while establishing that proxy also depends on DNS, startup can loop. Advanced configurations may use a separate upstream for resolving proxy-node domains, but that resolver must work before the proxy is established.

Check caches and listener conflicts

After changing DNS, account for Clash, system, and browser caches. Reload the configuration and restart the client first, refresh the system resolver cache next, then close and reopen the browser. Refreshing the page alone may reuse an old connection or browser cache. On Windows, use ipconfig /flushdns; on macOS, refresh the cache with the appropriate system command. On mobile, toggling Airplane Mode or restarting the network connection clears some state. Use clearing only for verification, not as a step required for every connection.

If Clash DNS needs to listen on local port 53, a system service, container tool, or other DNS program may already occupy it. The log will show a bind failure, leaving intercepted TUN queries without responses. Identify the process actually listening and decide which program owns DNS entry-point resolution. Do not let two services point upstream to each other. For example, system DNS pointing to a local filter, the filter pointing to Clash, and Clash pointing back to the system default can form a loop. The minimal chain needs one clear entry point and one clear external upstream.

Handle IPv6 and split DNS

When a domain returns both A and AAAA records, an application may try IPv6 first. If the device has an IPv6 address but the route is incomplete, requests wait for a timeout before falling back to IPv4, making DNS appear slow. Temporarily disable IPv6 responses in Clash DNS to test this. If the issue clears, inspect the router prefix, system default route, and node IPv6 support instead of treating every resolution problem as an upstream DNS failure.

Split DNS selects different upstreams by domain, which can reduce incorrect resolution, but its rules must match the proxy egress. If a domain is resolved by direct DNS but accessed through a proxy, the returned address may not be appropriate for that egress, and the reverse is also true. Check the domain, resolved address, and rule policy in the connection record. For a single-domain issue, add a precise rule as a test instead of immediately replacing global DNS. If one service keeps failing, check whether it depends on several related domains rather than only the hostname in the address bar.

07 · Enabled, but apps connect directly

System proxy not working: check the port, bypass list, and app proxy model

The system proxy affects only apps that honor system settings

When system proxy is enabled, the client points the operating system’s HTTP, HTTPS, or SOCKS proxy address to a local Clash port. Whether an app uses that setting is up to the app. Major browsers usually follow the system proxy, but games, command-line tools, store apps, virtual machines, and some cross-platform programs may ignore it completely. Therefore, “the browser works but one app connects directly” does not prove the system proxy switch is broken. First confirm the basic path with a browser that follows system settings, then check whether the target app supports an explicit proxy or requires TUN capture.

Check the server address and port in system settings. The address is usually 127.0.0.1, and the port must match the current mixed-port or HTTP port. After a configuration update or client switch, the port may change while the system keeps the old value. When using multiple clients such as Clash Plus and Clash Verge Rev, do not enable system proxy in both. The later program may overwrite the setting, and exit order may restore an older value. During troubleshooting, run only one client.

Verify browsers and command-line tools separately

A browser may have a standalone proxy extension whose settings override the system proxy. Disable the extension temporarily and restart the browser. A private window does not necessarily disable every extension; confirm this in the extension manager. Command-line tools commonly read HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables, which may not inherit the graphical system proxy. When setting variables, distinguish HTTP from SOCKS and note whether the setting applies only to the current terminal or to the global environment.

# Set an HTTP proxy for the current shell only
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# Clear it after testing
unset HTTP_PROXY
unset HTTPS_PROXY

Windows PowerShell, development tools, and containers each have their own proxy settings. Do not modify system, Git, package-manager, container, and editor settings all at once just to make one command work; restoring the environment later becomes difficult. Set the proxy temporarily in the current terminal and confirm that the request reaches the Clash log. If there is no log entry, the tool still is not using the specified proxy. If a request appears but fails, investigate rules or the node.

Check bypass lists and automatic configuration

System proxy settings usually include a list of hosts that bypass the proxy. localhost, LAN addresses, and corporate intranet hosts are commonly bypassed, but an overly broad wildcard can exclude ordinary domains by mistake. Windows may also have automatic detection or a PAC script enabled, while macOS stores proxy settings separately for different network services. If the system still shows a proxy after Clash is closed, check for an automatic proxy script, management policy, or another resident program. Record the original settings before editing, and do not forcibly remove policies from managed devices.

LAN addresses usually should use a direct connection so routers, printers, and file shares do not route through a proxy node. If LAN resources disappear after enabling TUN, inspect exclusion routes, private-address rules, and strict-routing settings. System proxy and TUN modes can cover different traffic; do not enable both and then treat the result as one undifferentiated test. Test system proxy alone first, then TUN alone. Only after both work separately should you decide whether to use them together.

Handle proxy settings left behind after exit

After a client crash, force-quit, or system shutdown, proxy settings may not be restored. A typical sign is that every app following the system proxy fails immediately after reboot while Clash is not running. Turn off the manual proxy in system network settings, then start the client and switch the system proxy on and off normally once. If this happens often, check for a service mode, daemon, or startup-permission problem, and use a currently maintained client version. Before reinstalling, export necessary settings and choose the correct platform installer from the Download Center.

Enterprise security software may block programs from changing the system proxy. The client toggle can look enabled even though the system value is unchanged, so checking the system proxy page directly is more reliable. The reverse can also happen: the system value changes, but security software blocks communication with the local listening port. Use a port-check command to confirm that Clash is listening, then see whether browser requests enter the log. The system setting, listening port, and logged request must all be present before the system proxy path is confirmed.

08 · Won’t start or keeps quitting

Client crashes: separate the UI, core, configuration, and system components

Identify the crash stage first

A client can crash at the startup screen, while loading a configuration, starting the core, enabling TUN, or updating a subscription. The stage determines the investigation. If double-clicking produces no window, check system event records, the application log directory, and security-software blocks. If the window appears and closes while loading a configuration, suspect invalid syntax, an oversized rule set, or an override script. If it exits only when TUN is enabled, focus on the virtual adapter, service permissions, and other VPN drivers. Do not report only “it will not open”; record the last visible screen and the last log entry.

Disable automatic restoration of the last configuration and startup launch first, so the program does not reload the broken state immediately. If the client offers safe mode or a custom configuration path, start with a minimal configuration. Without safe mode, exit the process, back up the configuration directory, and move the active configuration elsewhere so the client starts clean. Once the UI opens, do not immediately restore the whole directory. Import a basic configuration, confirm that the core runs, then restore subscriptions, overrides, and UI settings one at a time.

Separate UI issues from core issues

The graphical client manages configuration and system integration, while actual proxying is usually handled by a core process such as mihomo. If the UI is present but the core repeatedly stops, inspect core logs for configuration errors, port conflicts, and permission issues. If the UI is unresponsive while the core continues running, networking may still work; the issue is more likely UI cache, rendering components, or an oversized configuration list. Task Manager or Activity Monitor can show which process exited. Do not repeatedly launch multiple UI instances while the core is running; they may compete for the control port and configuration-file lock.

Validate syntax before investigating resource size. Large rule sets, too many proxy nodes, and frequent health checks increase startup time and memory use. A brief lack of response is not necessarily a crash; watch CPU, memory, and whether logs continue to change. If the client always stops after loading the same rule provider, disable that provider temporarily or clear its cache and retry. An incomplete remote rule file can also leave a corrupt cache; before deleting it, confirm that the subscription can download it again.

Check ports, permissions, and driver conflicts

The core may fail to start when the mixed, control, or DNS port is occupied. Use the earlier commands to identify the process and check whether the configuration accidentally defines the same listener twice. Low-numbered ports or TUN devices may need additional permissions, but running as administrator indefinitely should not be the only fix. Confirm that the client’s service component is installed correctly, system extensions are approved, and the virtual adapter exists. After a macOS upgrade, network extensions may require authorization again; Windows security policies may also block driver loading.

Other VPNs, virtual machines, container platforms, game accelerators, and security software may install network-filter drivers. Their background services can remain active even when the apps are closed. If crashes or disconnections occur only in TUN mode, fully stop those services and test again. If ordinary system proxy mode is stable, the core and node are probably fine and the problem is concentrated in the virtual-adapter path. Restore other network software one item at a time to identify the conflict instead of uninstalling everything at once.

The right order for reset and reinstall

Reinstalling the program usually does not remove user configuration, so a damaged setting can remain active afterward. First export necessary information other than the subscription URL, and record custom rules and ports. Then quit the client and back up its configuration directory. Rename the original directory so the new installation creates a clean configuration. After confirming that the empty state is stable, import the subscription again. Do not copy the entire old directory over the new one, or you will restore caches, window state, and broken settings together.

If system event records report missing runtime components, incorrect file permissions, or quarantine, follow the system’s repair guidance. The installer must match the processor architecture and platform; Apple Silicon and Intel, or Windows x64 and other architectures, cannot be mixed. See the Download Center for current client choices and platform support; Clash Plus is a practical desktop option. After recovery, enable startup launch and TUN one at a time, restarting to verify each, so a crash is not caused by startup order or restored permissions.

09 · Android and iOS

Mobile troubleshooting: background limits, VPN permissions, and network switching

Confirm VPN configuration and system status first

On Android and iOS, Clash-based clients usually capture traffic through the system VPN interface. The first connection requires explicit user authorization, and a VPN indicator should appear in the status bar. If the UI says connected but the indicator is absent, recheck system VPN settings and make sure no other VPN, enterprise security connection, or system network tool is using the same interface. Mobile systems generally allow only one active VPN; starting another app can disconnect the current one, while the client UI may take a few seconds to catch up.

On iOS, use Clash Plus and follow the iOS link in the Download Center to the App Store. On Android, compare Clash Plus, Clash Meta for Android, FlClash, and Surfboard in the Download Center. When migrating clients, do not keep two automatic connection profiles active. Disconnect the old client and disable its on-demand connection before importing the new configuration. Reimport the subscription, but record custom rules and overrides separately instead of copying unsupported platform fields directly.

Handle background termination and lock-screen disconnects

Android vendors’ battery policies may restrict the client, core, or VPN service after the screen turns off. Typical signs are normal operation while the screen is on, no network after several minutes locked, and immediate recovery when the app opens. In system battery settings, allow the client to run in the background, disable app-specific power saving, and permit auto-start or background activity. Menu names vary by vendor, but the checks are the same: does the VPN indicator disappear while locked, does the system report that the app was restricted, and was the persistent notification removed?

iOS manages background execution strictly, but an established system VPN is usually maintained by a network extension. If it disconnects frequently, check on-demand rules, Low Power Mode, system VPN configuration, and network-extension permissions. Do not repeatedly swipe the client away from the app switcher and then expect scheduled subscription updates. Update subscriptions manually when opening the app, and judge connection stability by the system VPN status. Very low storage or an ongoing system update can also affect configuration writes and extension startup.

Switching between Wi-Fi and cellular

Switching from Wi-Fi to cellular changes the local address, DNS, MTU, and IPv6 environment, so existing connections must be rebuilt. A brief interruption is normal; if recovery does not occur, disconnect and reconnect the VPN manually and watch for a new node connection. If cellular works but a particular Wi-Fi network does not, check whether that Wi-Fi requires web authentication, restricts VPN traffic, or provides problematic IPv6 or DNS. On public Wi-Fi, disconnect the proxy first, complete authentication in a browser, then connect the client.

If the issue occurs only on cellular, check whether the client is blocked from using mobile data, whether Data Saver is enabled, and whether the subscription or node domain resolves through cellular DNS. On dual-SIM devices, confirm the active data SIM and network-switching policy. Some systems switch data SIMs when signal conditions change, invalidating existing connections. For diagnosis, lock the device to one data SIM, disable smart switching, and test the same node. Once it works, re-enable automatic switching gradually to see whether reconnecting after each network change is necessary.

Per-app proxying and LAN access

Android clients often offer per-app proxying, allowing you to proxy only selected apps or exclude selected apps. A wrong setting can make the browser work while the target app connects directly, or prevent system components from reaching the network. Temporarily disable per-app rules so every app uses the same connection. After confirming normal behavior, add exclusions one at a time. App updates, package-name changes, and work profiles can invalidate earlier selections; personal and work profiles may also have different VPN permissions. Connection logs can confirm whether the target app’s requests reach the core.

For home routers, casting devices, and LAN services, allow private addresses to connect directly. If LAN devices cannot be discovered after connecting the VPN, check the client’s “Allow LAN access” option, private-address rules, and system local-network permission. iOS asks separately for local-network access; denying it can leave the proxy working while device discovery and LAN connections fail. Android may also require nearby-device or location-related permissions to scan for LAN services. These permissions are unrelated to whether the proxy node works.

Minimal mobile recovery process

For persistent mobile disconnections, follow a fixed order: disconnect the client, confirm that basic networking works with the VPN off, toggle Airplane Mode once, restore the network, open the client, select one specific node, reconnect in Rule mode, and check the system VPN indicator and client log. If it still fails, compare Wi-Fi with cellular. Do not clear app data and delete the subscription at the same time, or you will lose evidence of the original failure. Reset only after confirming that the configuration cannot load or the app state is damaged, and back up necessary settings first.

If the issue remains after reinstalling, the cause is usually the system VPN configuration, network environment, subscription, or node—not the application files. Delete stale VPN profiles from system settings, restart the device, and let the current client request permission again. If one app is affected, check its Private DNS, data permission, and per-app proxy settings. If every app is affected, return to the node, DNS, and network-switching path. The key to mobile troubleshooting is still one variable at a time: establish one successful connection with a fixed client, node, and network before restoring auto-selection, background policies, and per-app rules.

If the issue remains unresolved after following this page, prepare a minimal report: device and platform, client name, network in use, current mode, whether TUN is enabled, one reproducible destination, the exact steps from working to failing, and relevant logs with subscription details removed. State whether closing the client restores access, whether switching to a hotspot helps, and whether other nodes work. These comparisons identify the failing layer far better than “it cannot connect” and help avoid exposing subscription links or private network information.