Clash Troubleshooting Guide

1. General Approach: Locate the Problem, Then Treat It

The worst way to troubleshoot is tweaking one thing here, another thing there, and ending up with no idea what actually fixed it. Before touching anything, build a mental map: a single proxy request travels through the following stages on its way out and back. A problem in any one of these stages shows up as "no internet," but the fix is completely different depending on which one.

Application → System Proxy / TUN Mode → Clash Core (Local Port) → Rule Matching (Proxy Groups) → Node → Target Website

Breaking it down: first, does the app actually route traffic through the system proxy — some apps (certain games, CLI tools) ignore system proxy settings by default; second, is the system proxy actually set, and does its port match the Clash core's listening port; third, once the core receives the request, it matches it against the rule set line by line to decide direct connection or a specific proxy group, which then picks a node; fourth, is the node alive, is its protocol supported by the core, and is it being blocked along the way. Wherever the failure is, that's the chapter to check.

Three Ground Rules

1. Locate the stage before you touch anything. Figure out which stage of the chain is failing first, then find the fix in the matching chapter. Changing settings blindly is a coin flip — you might fix it by luck, or introduce a new problem.
2. Change one variable at a time. Change one thing, test it, then move on. Change three things at once and you won't know what fixed it if it works, or what broke it if it doesn't — troubleshooting turns into a rabbit hole.
3. Check the logs before drawing conclusions. Logs are Clash's medical chart: whether a request came in, which rule it hit, what error it threw — it's all there. Before troubleshooting, bump the log level from the default warning up to info or debug, reproduce the issue, then read the log. Error level only records fatal errors; info shows where every connection went; debug is the most detailed (and noisiest) — switch it back once you're done.

Three Basic Tests

The following three tests come up throughout this guide, and later chapters will send you back here repeatedly:

Test 1, local port test — verifies whether the path from core to node is working:

If it returns an HTTP response header, the core, rules, and node are all working, and the problem is in the system proxy or application layer. If it times out or errors immediately, something's wrong between the core and the node. Port 7890 is a common default — check the mixed port shown in your client for the actual value.

Test 2, latency test — the latency test in the client panel only shows whether a node can establish a TCP connection; it says nothing about speed. All nodes timing out and individual nodes timing out are two different problems, covered by two separate paths in Chapter 3.

Test 3, direct-connection baseline — temporarily disable the system proxy (or quit the client) to confirm your local network can reach the internet at all. If it can't, fix your local network first — Clash can't fix that.

2. No Internet After Connecting

Symptom The client shows it's running, the system proxy toggle is on, but the browser can't load any pages — or only some sites load while others spin until they time out.

Diagnostic Sequence

1. Check whether new connections appear in the logs. Open the client's log panel and reload the page that won't load. If nothing new shows up in the logs at all, the request never reached Clash — the system proxy isn't applied. Skip straight to Chapter 7. If entries do appear, keep going.
2. Test with global mode. Switch the proxy mode from "Rule" to "Global," then reload the page. If it loads in global mode, the core and node are both fine, and the rules are sending your request to a direct connection or the wrong proxy group — see "Rules Misfiring" below. If it still won't load, keep going.
3. Test by switching nodes. Manually pick a different node in the proxy group, then reload. If switching nodes fixes it, the original node is faulty — go to Chapter 3. If several nodes in a row all fail, keep going.
4. Check whether TUN and the system proxy are conflicting. Running TUN mode and the system proxy at the same time can create a loop on some systems, where traffic bounces between the two layers and every request times out. Turn off one of them and test again.
5. Check for security software interference. Some antivirus tools and firewalls block loopback connections on the local proxy port, or block the Clash core's outbound traffic directly. Disable it temporarily and retest; if that's the culprit, whitelist the client and re-enable protection.

Rules Misfiring: Global Mode Works, Rule Mode Doesn't

In rule mode, every request is matched against the rule set top to bottom: a match on DIRECT goes direct, a match on a proxy group goes through the proxy, and anything that matches nothing falls through to the catch-all rule. Whether a site loads depends entirely on which rule it hits. Three common misfires:

• Outdated rule set: A newly registered domain isn't in the rule set yet and gets sent direct by the catch-all rule. Update your subscription or rule data (GeoIP / GEOSITE) and try again.
• Custom rule typo: A manually added rule has a misspelled domain suffix, or is placed too high and intercepts requests too early. Rules match top to bottom — temporarily comment out the suspect custom rule and test again.
• Proxy group pointing to a dead node: The target site matches a proxy group, but the currently selected node in that group is dead. Switch to another node in the group, or set the group to url-test for automatic selection.

Only One App Can't Connect

If the browser works fine but a specific app just won't go through the proxy, it's usually because that app doesn't read system proxy settings — common with some games, CLI tools, and desktop apps. Two fixes: enable TUN mode, which intercepts traffic at the network interface level regardless of whether the app cooperates; or manually set the proxy to 127.0.0.1:7890 in that app's network settings. See the end of Chapter 7 for when to use TUN mode and its trade-offs.

3. Node Timeouts and Connection Failures

Symptom The latency test shows timeouts across the board; or a single node is flagged red, and the logs repeatedly show connect timeout, connection refused, or handshake failure.

First, Determine: All Nodes or Just a Few?

If every node times out at once, the problem is almost always local or on the subscription side — dozens of nodes failing simultaneously is extremely unlikely. If only a handful of nodes time out, then it's likely the nodes themselves. These two cases require completely different approaches, so figure out which one you're dealing with first.

All Nodes Timing Out: Check These Four Things in Order

1. Local network: Turn off the proxy and connect directly to confirm your own network is working. If it isn't, fix that first — nothing else matters until you do.
2. Subscription status: Log into your provider's dashboard and check whether your plan has expired or your data is used up. Once a subscription expires, the node list often stays visible in the client, but every node becomes unusable — this is the most common cause of "all nodes down." Once confirmed, go to Chapter 4 to update your subscription.
3. System clock: TLS handshakes check certificate validity against the system time. If your clock is off by more than a few minutes, every node's handshake will fail, which looks exactly like all nodes being down. Sync your system time and retry — this one gets overlooked a lot.
4. Local ports and firewall: If the core's proxy port is taken by another program, or blocked by a firewall, every request fails. See Chapter 8 for how to check port usage.

A Few Nodes Timing Out: Check These Three Things in Order

1. Node failure or blocking: Backbone network congestion during peak hours, or a node's IP being blocked in the target region, both show up as single-node timeouts. Try a node in a different region or with a different entry point for comparison.
2. Protocol/core mismatch: If your subscription mixes multiple protocols, an older Clash core may not recognize newer protocols like VLESS or Hysteria2, so those nodes all show as unusable while the rest work fine. Switch to a mihomo-core client to fix this — every client listed on the download page uses the mihomo core.
3. Changed node parameters: If your provider changed a port, password, or entry address and your local subscription hasn't been updated, the old parameters simply won't connect. Update your subscription and retest.

4. Subscription Update Failures

Symptom Clicking "Update Subscription" throws an error: download failed, request timed out, parse failed, or config is empty; or the update button spins for a while with no change to the node list.

Diagnostic Sequence

1. Paste the subscription link directly into a browser and open it. If it downloads a text file (YAML or Base64 content), the link works and the problem is on the client side — go to step 2. If it won't open, returns a 404/403, or redirects to your provider's announcement page, the link is dead or your plan has an issue — go to step 3.
2. Client side: disable "update subscription via proxy" and try again. This creates a circular dependency: if the proxy is already down, updating through the proxy will always fail — and without new nodes, the proxy can't come back up. Always update your subscription over a direct connection. If it still fails, check whether TUN mode is intercepting the update request too; if needed, quit the client, download the subscription in a browser, and import it manually.
3. Link side: go back to your provider's dashboard and re-copy the subscription URL. If the dashboard has reset the subscription token, the old link is invalid. When a plan expires or data runs out, some providers return an empty response or an error page until you renew. If you're using a subscription converter, the converter itself may be down — try the provider's original subscription link instead.

Downloads But Fails to Parse

A parse failure means the client received something in a format it doesn't recognize. Three common cases:

• An HTML error page was returned: The subscription URL is being blocked by a reverse proxy or converter, returning a webpage instead of a config. Open the link in a browser to check.
• Format mismatch: The subscription content is in a format meant for a different client (some dashboards default to a different output format). Set the output format to Clash / mihomo in your provider's dashboard or converter link parameters.
• Truncated content: Network hiccups can cause an incomplete download, leaving the YAML structure broken. Update again, or download the full file in a browser and import it manually.

Manual Import as a Fallback

If the subscription URL can't be fixed right away, save the content you were able to open in a browser as a .yaml file and use "Import from File" in the client. Local files don't auto-update, so once the subscription is working again, remember to switch back to the URL method — otherwise node changes will never sync in. For more on managing configuration profiles — switching between multiple profiles, merging, update strategies — see "What Is a Clash Configuration Profile".

5. Slow Speeds, Stuttering, and Buffering

Symptom The proxy connects fine, but pages load slowly, video keeps buffering, or download speeds are far below expected — or it's fine during the day and stutters every evening, on a predictable schedule.

First, Figure Out Where the Slowdown Is

Run a comparison: run a speed test with the proxy off (direct), then run it again with the proxy on. If direct is already slow, the problem is your local broadband or Wi-Fi — fix that first. If direct is fine but the proxy is slow, the bottleneck is the node or the rules — keep reading.

Latency Numbers Don't Equal Speed

The latency test in the client only measures how many milliseconds it takes to establish a TCP connection — it has nothing to do with bandwidth. A node with 300ms latency might max out a 100Mbps connection, while an 80ms node might only manage a few Mbps. Don't pick nodes by latency ranking — judge by how pages actually load, how smoothly video seeks, or run an actual speed test.

Three Node-Side Causes of Slowness

• Peak-hour load: Between 8pm and 11pm, nodes are at their most congested, and the same node can run several times slower than during the day. Switch to a less-loaded node during this window, or try a different region.
• Routing detours: The route quality between a node and the target site determines your experience. Accessing a Japanese site through a US node means the data crosses the Pacific twice. Pick a node geographically close to the target site.
• Rate multipliers and throttling: Some providers throttle low-multiplier nodes or limit per-connection speed. Route large transfers (system updates, cloud sync) through direct-connection rules instead of eating into your proxy bandwidth.

Two Rule-Side Causes of Slowness

• Traffic routed to the wrong proxy group: Open the logs and check which rule the target domain matched and which group it was assigned to. If a streaming domain ends up in a "catch-all direct" group, it'll be slow and may not even unlock region-restricted content.
• Auto-select group misbehaving: url-test groups pick nodes by latency, which may select a low-latency but low-bandwidth node. Switching key proxy groups to manual selection during peak hours can actually be more stable.

Two Local-Side Causes of Slowness

• TUN mode overhead: TUN processes all traffic at the network interface level, which adds overhead during heavy downloads. For maximum speed, routing the browser through the system proxy while letting the download manager connect directly is a better combination.
• Double-proxying: Running the system proxy and TUN together, or stacking a browser proxy extension on top of the system proxy, adds an extra hop and cuts into your speed for nothing. Keep only one layer active at a time.

For a systematic approach to picking nodes — weighing latency, rate multiplier, region, and protocol — see "How to Choose a Proxy Node".

6. DNS Resolution Issues

Symptom The browser shows "server IP not found"; some domains won't load while their IP addresses connect fine; or the first page load takes forever but the second one is instant.

First, Understand Clash's Two DNS Modes

The Clash core's built-in DNS module supports two resolution strategies, each with different behavior and compatibility — picking the wrong one causes the symptoms above:

Diagnostic Sequence

1. Confirm it's actually a DNS issue. If a site that won't load connects fine when you use its IP directly (or works on another device over cellular), the problem is almost certainly in resolution, not the node.
2. Check your current DNS config. Verify dns.enable is set to true in your config, and that any "DNS takeover" toggle in the client UI hasn't been switched off. If the core isn't handling DNS, poisoning and hijacking hit the system resolver directly.
3. Check fake-ip compatibility. If the problem is concentrated on games, LAN services (printers, NAS, screen mirroring), or certain banking/government apps, it's highly likely fake-ip incompatibility. Add these domains to fake-ip-filter, or switch the whole setup back to redir-host mode.
4. Check for ISP hijacking. Home broadband default DNS often hijacks plaintext queries on UDP port 53 and returns tampered results. Configure your nameserver to use DoH/DoT encrypted resolution and the hijacking stops working.

A DNS Config You Can Copy Directly

dns:
  enable: true
  listen: 0.0.0.0:53
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "*.home.arpa"
    - localhost.ptlogin2.qq.com
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query

How it works: nameserver handles domestic domains for fast resolution; fallback handles international domains through an encrypted channel to prevent poisoning; fake-ip-filter lists domains that don't tolerate fake addresses, using the wildcard syntax shown above. Restart the core after editing the config for changes to take effect.

Verification command:

If it returns an address in the 198.18.x.x range, fake-ip is working. If it times out, the core's DNS isn't running — go back to step 2 and check dns.enable and the listening port.

7. System Proxy Not Working

Symptom The client is running and nodes are healthy, but no new connections ever show up in the logs; the system settings show no proxy entry, or the proxy entry points to a port that doesn't match the client.

Confirm the System Proxy Was Actually Set, by Platform

Common Reasons the Proxy Isn't Applied

1. Insufficient permissions: Writing the system proxy requires certain permissions. On Windows, a client running with standard privileges may be blocked by group policy; on macOS, the first time you enable it triggers an authorization prompt — if you clicked "Don't Allow," enable it manually in the network proxy settings.
2. Browser extension overriding it: Extensions like SwitchyOmega take over the browser's proxy settings entirely and ignore the system proxy, following their own rules instead. This shows up as "the system proxy is clearly on, but the browser doesn't use it." Disable the extension, or switch it back to "use system proxy" mode.
3. Leftover settings from other proxy software: A previously installed VPN or accelerator may have left the system proxy pointing at its old port without cleaning up on exit. Manually reset the system proxy to 127.0.0.1 and the current client's port, or turn it off and let the client rewrite it.
4. Port mismatch: Different clients use different default ports (commonly 7890, sometimes 7897), and the config's mixed-port may have been changed while the system proxy still points to the old value. Make sure both match, or toggle the system proxy off and back on in the client so it rewrites the setting based on the current config.

Manual Setup and TUN as a Fallback

If automatic setup keeps failing, you can manually enter the proxy in system settings: address 127.0.0.1, port matching the client's mixed-port. The downside of manual setup is that the system proxy won't clear itself when the client quits — turn it off manually before shutting down, or your entire network will be broken next time you start up without launching the client.

A more thorough fix is TUN mode: it intercepts all traffic at the network interface level, doesn't depend on the system proxy, and works even with apps (games, CLI tools) that ignore system proxy settings. The trade-off is needing to install a service or grant admin/root privileges, and running it alongside the system proxy can cause a loop — use one or the other. On Windows, run the client as administrator before enabling TUN; on macOS, authorize the helper tool installation when prompted; on Linux, you'll need root or configured capabilities.

8. Client Crashes and Startup Failures

Symptom Nothing happens when you launch the client, it crashes immediately, a "core failed to start" error appears, the UI freezes and stops responding, or it silently quits after auto-starting on boot.

First, Get the Real Error Message

If the GUI crashes immediately, launch the client from the command line, or start the core on its own — the error will print directly in the terminal. That error text is your starting point for everything in this chapter; get it first, then check it against the four common causes below. The GUI swallows the error, and guessing based on an icon won't get you anywhere.

Four Common Causes

Configuration Syntax Errors

YAML is extremely sensitive to indentation: it must use spaces, align consistently at each level, never use tabs, and every colon must be followed by a space. If the core won't start after you manually edited the config, it's almost always an indentation or punctuation issue. Revert your change, or run the config through a YAML validator before launching.

Port Already in Use

If the proxy port (default 7890) or the external control port (default 9090) is taken by another program, the core will start and immediately quit. Check what's using it:

The first command is for Windows, the second for macOS/Linux. If the process using it is a leftover Clash instance that didn't fully exit, kill it and restart; if it's some other software, change the client's port or that program's port instead.

Insufficient Permissions

TUN mode and enhanced mode require elevated privileges — without them, the core fails to start or the TUN interface fails to come up. On Windows, right-click and "Run as administrator"; on macOS, enter your password when prompted to install the helper; on Linux, use sudo or grant capabilities with setcap.

Corrupted Config Directory

An unexpected power loss or forced quit can corrupt the cache or config index, causing the client to open fine but crash on any action. Back up your subscription links and custom rules first, then delete the config directory to let the client rebuild it. Config directory locations: on Windows, a folder named after the client under %APPDATA%; on macOS, ~/Library/Application Support/; on Linux, ~/.config/.

Antivirus False Positives

Some security software flags the proxy core as suspicious and blocks or quarantines it. Typical signs include the core file suddenly disappearing, or it getting blocked after every update. Whitelist the client's install directory and config directory, restore any quarantined core file, then restart.

9. Mobile-Specific Troubleshooting (Android / iOS)

Symptom On Android, traffic drops after locking the screen or switching apps; on iOS, the connection drops after running in the background for a while; or mobile-specific issues like "the VPN icon disappears" or "the toggle switches off by itself."

Android-Specific

1. Battery optimization killing the background process (most common): Many Android skins from Chinese manufacturers aggressively kill background apps by default, shutting down the proxy core within minutes of locking the screen. Go to system settings and add the client to the battery optimization whitelist, allow auto-start, and lock it in the recent apps list. The exact menu location varies by manufacturer (Xiaomi: "Battery & performance"; Huawei: "App launch management") — search "battery optimization" in settings if you can't find it.
2. VPN slot conflict: Android only allows one app to hold the VPN service at a time. If another VPN, accelerator, or ad-blocking app has taken the VPN slot, Clash's toggle will get kicked off. Stop the conflicting app and try again.
3. Per-app proxy settings: If "per-app proxy" in the client excludes your target app, that app will appear to bypass the proxy. Check the app list, or temporarily switch to "proxy all apps" to compare.
4. Private DNS conflict: When the system's "Private DNS" is enabled, it bypasses the proxy's DNS handling, which can cause resolution issues in some cases. If the proxy behaves oddly, try disabling Private DNS to compare.

iOS-Specific

1. Background refresh limits: iOS strictly limits background network activity — after locking the screen or switching away for a while, the connection may be suspended by the system and automatically reconnect when you return to the app. This is normal system behavior, not a bug. If disconnects happen often, check whether Low Power Mode is on, since it further restricts background activity.
2. VPN profile conflicts: If you've installed multiple proxy-related apps, the system may have leftover VPN profiles that interfere with each other's toggles. Go to "Settings → General → VPN & Device Management" and remove any profiles you're not using.
3. Wi-Fi/cellular switching: When your network switches, the proxy tunnel has to rebuild, causing a few seconds of disconnection — this is a normal part of reconnecting. If it doesn't recover after a while, toggle Airplane Mode on and off to force a reconnect.

Choosing a mobile client: on Android, Clash Plus is recommended, with Clash Meta for Android and FlClash as alternatives; on iOS, Clash Plus is recommended (available on the App Store, official site clashplus.io). See the client comparison page for a detailed breakdown, and the download page for installers.