Clash Troubleshooting Handbook

Before You Start: Diagnostic Approach and Information Gathering

Troubleshooting rewards method over luck. This chapter doesn't fix any specific problem, but it determines how fast and accurately you can work through every other chapter. Three minutes here can save an hour of trial and error later.

Three Diagnostic Principles

Change one variable at a time. Many people hit a problem and immediately switch nodes, change modes, restart the client, and reboot the computer all at once. Even if it works afterward, you won't know which step actually fixed it, and you'll be stuck guessing again next time. The right approach: change one thing, verify it, write it down.

Work outward from your own end. The full chain is "app → system proxy / TUN → client → node → target site." The closer to the left, the easier it is to check yourself; the closer to the right, the more it depends on third parties. Confirm your own half is clean before blaming nodes or your subscription provider — doing it backward wastes time.

Every step needs a verification action. "It feels like it's working now" doesn't count — you need a concrete check: a curl command, a latency test, or the result of loading a fixed site. Every chapter in this handbook gives you a matching verification method.

Gather This Information Before You Start

• The client name and platform (e.g. Clash Plus / Windows, Clash Verge Rev / Linux) — setting locations vary by client, but the diagnostic logic applies across all of them;
• The current proxy mode: Rule / Global / Direct, and whether TUN (virtual network adapter) mode is on;
• The subscription source: whether the link comes straight from the provider or has passed through a conversion service;
• The most recent error line in the client log — almost every client has a log panel; set the level to info and reproduce the issue once;
• Whether the problem has always existed or started after a specific change. For the latter, simply rolling back that change is often faster than diagnosing it.

Symptom Quick Reference

Not sure which chapter to check? Find your symptom in the table below and jump straight to it.

Symptom 1: Proxy Is On, But There's No Internet Access

Bottom line first: 90% of these cases come down to two things — traffic never reaching the client (system proxy not set, or hijacked by another app), or traffic reaching the client but not getting out (wrong mode, a rule blocking it, or all nodes down). One command can split these two apart — don't rush to reinstall.

Step 1: Hit the Client Port Directly with curl

Open the client's settings page and note the mixed port (7890 is a common default, but always use whatever your client actually shows — don't copy it blindly from a tutorial). Then run this in a terminal / command prompt:

curl -x http://127.0.0.1:7890 -I https://www.gstatic.com/generate_204

This command bypasses the system proxy and forces traffic through the client port directly. There are only two possible outcomes:

• Returns 204 or any HTTP response headers: the client-to-node half is working fine, and the issue is "traffic isn't getting in" — skip to the next section on the system proxy;
• Connection refused / timeout: traffic is reaching the client but can't get out — the issue is in the client config or the node — skip to the "Traffic Can't Get Out" section.

Traffic Not Getting In: Check the System Proxy and Browser Extensions

Confirm the "System Proxy" toggle is on in the client, then check the system settings to verify the proxy was actually written there (see the comparison table in the System Proxy chapter for where to check on each platform). If it's set correctly and still doesn't work, focus on three usual suspects that "steal" traffic:

• Browser proxy extensions: extensions like SwitchyOmega take priority over the system proxy. If the extension is configured with a dead proxy, the browser breaks entirely. Switch the extension to "use system proxy" or disable it and try again;
• Leftover proxy software: a previously installed proxy tool wasn't fully uninstalled, didn't restore the system proxy on exit, or launches at startup and overwrites the current client's settings. Check the task manager and fully quit anything you're not using;
• Security software and corporate policies: some security software locks proxy settings, and work computers may have Group Policy forcing a specific proxy. These environments need the lock removed first.

Traffic Can't Get Out: Check the Mode and Rules

1. Check the proxy mode. In Direct mode, no traffic goes through any node — turning the proxy on does nothing. New users trigger this switch by accident fairly often.
2. In Rule mode, open the client's Connections / Logs panel, visit the site that won't load, and see which rule matched the connection and which proxy group it landed in. If it hit REJECT, a rule is blocking it; if the matched group's selected node is dead, just pick a different node.
3. Run a "Global test": switch to Global mode, manually pick a node that just tested with normal latency, and try again. If Global works but Rule doesn't, the problem is almost certainly in your rules or group selection.

The Pitfall of Running TUN and System Proxy Together

With TUN mode and the system proxy both on, the traffic path becomes hard to reason about — some connections go through the virtual adapter, others through the system proxy, and the logs can look contradictory. Keep only one path active while troubleshooting — either turn off TUN and use only the system proxy, or turn on TUN and turn off the system proxy. Restore your usual combination once you've found the issue.

Symptom 2: Node Latency Tests Time Out

A screen full of "timeout" in the latency column is alarming, but keep two things straight: a latency timeout doesn't automatically mean the node is unusable. Latency tests have the node hit a fixed test address — some nodes just don't play nice with that specific address while working fine for actual browsing. The reverse also happens: good-looking latency numbers on a node that can't actually load pages. Real usage is the final judge; latency is only a reference.

All Nodes Time Out: Check Your Local Network and Subscription First, Not the Nodes

When every node times out at once, a mass node failure is actually the least likely explanation — the problem is more likely on your side:

1. Confirm your local network is working: turn off the proxy (or switch to Direct mode) and open any regular website. If even that fails, fix your local network first — this isn't a client problem;
2. Confirm the subscription is still active: an expired subscription, used-up data, or a link the provider reset will kill every node at once. While on Direct mode, log into your provider's site to check status, then manually update the subscription in the client;
3. Check the test URL: some clients let you customize the latency test URL. If it's been changed to an address that's unreachable in general, everything will time out. Reset it to a default like generate_204 and test again;
4. Cross-check with a different client: import the same subscription into another client (the Downloads page lists alternatives for all five platforms). If the other client works fine, the problem is in the original client's settings — focus on the port, TUN, and DNS settings.

Some Nodes Time Out: Diagnosing Node-Side Issues

When only some nodes time out, the fix is actually simpler:

• Timeouts cluster by region: an international route is down or under maintenance. Switch to nodes in a different region for now and check back in a few hours;
• The same few nodes are always down: these nodes are likely offline but haven't been removed from the subscription — report it to your provider;
• Everything slows during peak hours with occasional timeouts: a classic sign of route congestion, covered in the Slow Speeds chapter — switch to a less popular region to ease it;
• Timeouts started after changing networks: some networks (campus, corporate) block specific ports or protocols — try nodes on different protocols or ports within the same subscription.

Symptom 3: Subscription Import or Update Fails

The upside of subscription problems is that the error message is usually blunt; the downside is many clients tuck the error away in the logs instead of showing a popup. After an import / update failure, the first move is to open the log panel, find the red error line, and match it against the table below.

Error Message Reference

Manually Verify the Subscription Link with a Command

If you can't tell whether the link is broken or it's a client issue, use curl to simulate the client pulling the subscription (the example link below is fake — swap in your own):

curl -A "clash" -I "https://example.com/api/sub?token=xxxx"

If it returns 200 with headers like subscription-userinfo, the link itself is healthy and the problem is on the client side; a 404 / 403 means you should get a new link from the provider's dashboard. Note the -A "clash" flag: many subscription services serve different formats based on User-Agent, so what you see opening the link in a browser can differ from what the client actually pulls. Use a clash-style UA when verifying, or the test isn't meaningful.

Import Succeeds But the Node List Is Empty

This kind of "fake success" is usually a format issue: the subscription returned a generic sharing format instead of a Clash config, or an older-core client silently skips nodes using newer protocols. Two fixes: ask the provider for a dedicated Clash-format subscription endpoint, or confirm you're using a mihomo-core client (all the main clients on the Downloads page are) — full support for newer protocols and better compatibility with older formats.

More subscription Q&As — auto-update intervals, running multiple subscriptions, data usage not displaying — are collected in the FAQ's "Setup & Configuration" category.

Symptom 4: Connected, But Speeds Are Slow

"Slow" is the hardest symptom to diagnose because the bottleneck could be anywhere along the chain. This chapter's core method fits in one sentence: use cross-testing to isolate which segment is the bottleneck, then optimize that segment — don't jump straight to switching subscriptions.

Three-Way Cross-Testing

1. Same node, different targets: with your current node, open three or four different sites. If all of them are slow, suspect the node or your local network; if only one is slow, it's the target site itself or a route it doesn't get along with — switching node regions helps;
2. Same target, different nodes: try two or three nodes in different regions against the same site. If it's slow no matter which one, focus on your local network; if switching regions speeds things up, the original node was congested;
3. Direct mode for a baseline: switch to Direct mode and run a local speed test. If even direct is slow, fix your broadband and Wi-Fi first — a proxy can never be faster than your baseline speed.

Node Side: Congestion, Rate Multipliers, and Protocols

Slowdowns during peak hours are normal for shared routes — fast during off-hours and slow during busy ones is basically confirmation of congestion, and switching to a less popular region is the most direct fix. Also watch for the rate multiplier shown in your subscription — higher-multiplier nodes usually run pricier routes with a different speed profile, and whether it's worth it is your call. If the same provider offers multiple protocol endpoints, switching between them for comparison helps too — different protocols perform quite differently depending on the network.

Client Side: Mode and Settings

• Use Rule mode day-to-day, not Global: in Global mode, even local sites route through a node, forcing all your traffic through a bottleneck. Rule mode lets direct-eligible traffic go direct, which is the best balance of speed and experience;
• Set the log level back to info: debug logging generates a huge volume of entries and drags on performance if left on — remember to switch it back once troubleshooting is done;
• Check for multiple proxy layers: a proxy group set to "relay / chain" mode, or another proxy tool wrapped around the client — every extra hop costs speed;
• An oversized ruleset: tens of thousands of custom rules written inefficiently (lots of regex) push up matching overhead — trim the rules or switch to a rule-provider that loads on demand.

Device and Network Environment Side

Weak Wi-Fi signal, a crowded 2.4GHz band, or an underpowered router will all become the floor for your entire connection. Worth a special note on running the core directly on a router: if a software or bypass router doesn't have the horsepower, running a proxy on it will drag down speeds for the whole household — see the blog's overview of running mihomo directly on a router for hardware guidance. Also check whether a download manager or cloud sync tool is saturating your upload in the background — once upload maxes out, every connection's performance falls apart.

Symptom 5: DNS Resolution Issues

DNS problems are the most elusive kind of failure, with symptoms all over the map: node latency looks fine but pages just spin, some direct sites resolve to a strange region, or LAN devices suddenly can't be found. If you've ruled out nodes and the system proxy and something's still off, it's probably DNS.

Understand fake-ip and redir-host First

Clash-family cores have two DNS enhancement modes: fake-ip returns a fake IP from a reserved range for every domain, then matches rules by domain once the connection comes in — fast and accurate, and the current default in most setups; redir-host returns the real resolution result, used for compatibility. For the full differences and when to use each, see the entry in the Glossary and the blog's detailed DNS configuration guide — this section only covers troubleshooting.

Common Symptoms and Fixes

• Pages just spin, but node latency is normal: the upstream DNS in nameserver is likely unreachable, stalling resolution. Switch to a reachable DoH address and try again;
• Some domestic sites resolve overseas and load oddly: routing picked up an overseas result from fallback — check whether fallback-filter has geoip fallback configured;
• LAN devices, NAS, or printers can't be found: fake-ip is hijacking LAN domains too — add entries like *.lan and +.local to fake-ip-filter;
• Things stay broken for a while after quitting the client: the system cached a fake-ip resolution — flushing the system DNS cache fixes it.

A DNS Block You Can Use Directly

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "+.msftconnecttest.com"
  nameserver:
    - https://223.5.5.5/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

The logic is simple: nameserver handles everyday resolution — pick something directly reachable and fast; fallback covers overseas domains, paired with the geoip rule in fallback-filter — trust nameserver if the result lands on a domestic IP, otherwise use the fallback result to avoid poisoning.

Verifying After Changes

After reloading the config, send a query directly to the client's DNS listening port (port 1053 in the config above):

nslookup -port=1053 www.gstatic.com 127.0.0.1

In fake-ip mode, an address starting with 198.18 means it's working correctly. Also remember to flush the system cache so old results don't skew your read:

# Windows
ipconfig /flushdns

# macOS
sudo killall -HUP mDNSResponder

Symptom 6: System Proxy Not Working

Understand the mechanism first, and every strange behavior after this makes sense: turning on "system proxy" in the client just registers an HTTP/SOCKS proxy address in the OS's network settings. Whether an app reads that registration is entirely up to the app. Browsers do, so browsers go through the proxy; many command-line tools and some desktop apps don't, so they connect directly as usual. That's not a bug — that's how the mechanism works.

Where to Check the System Proxy on Each Platform

If the toggle is on in the client but the system settings show nothing, the write failed: check whether the client has permission to modify network settings, and whether some other software keeps reverting it (leftover proxy tools and certain security software both do this). Linux desktops have more pitfalls — GNOME and KDE each have their own proxy settings, and the terminal follows environment variables, with all three independent of each other. See the blog's two deployment paths on Linux for details.

Command-Line and Dev Tools Need Feeding Separately

Tools like curl, pip, and npm in a terminal don't read the system proxy by default — they need environment variables (swap in your client's actual port):

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7891

Git has its own config option — a common way to set it is git config --global http.proxy http://127.0.0.1:7890, and remember to --unset it when you're done. If a desktop app has a "network settings" or "use system proxy" toggle of its own, turn it on inside the app first — much cleaner than messing with global settings.

Don't Want to Configure Each One: Use TUN Mode

TUN mode creates a virtual network adapter and takes over all traffic at the network layer, with no cooperation needed from any app — it covers command-line tools, games, and UWP apps that the system proxy can't reach. The cost is that it needs admin / system extension authorization, and DNS needs to be configured correctly (paired with the fake-ip setup from the previous chapter). The toggle location and authorization steps vary by client — see the corresponding section in the User Guide; for a conceptual explanation, see the TUN entry in the Glossary. Turn off the system proxy once TUN is on, for the same "keep one path active" reason covered in Symptom 1.

Symptom 7: The Client Crashes or Won't Start

Crashes look scary but actually have the most concentrated set of causes: config syntax errors and port conflicts together cover the vast majority of cases. Check in the order below and you'll usually have an answer within ten minutes.

Suspect #1: Config File Syntax

If crashes started right after importing a new subscription or hand-editing the config, it's almost certainly a config problem. The cleanest way to check is a syntax validation straight from the core — mihomo has a built-in flag for this (the core binary is available in the Cores section of the Downloads page):

mihomo -t -f /path/to/config.yaml

If there's an error, it'll point out the line number and reason directly. The three most common hand-editing mistakes: YAML indentation using tabs or wrong nesting, full-width quotes accidentally pasted in, and duplicate keys at the same level. Fix them one by one against the error. If you can't figure it out, revert to the last working config so the client can run again.

Suspect #2: Port Conflicts and Leftover Processes

If a previous client instance didn't fully quit, or another piece of software is holding the same port, a new instance simply can't start. Check what's holding the port first:

# Windows
netstat -ano | findstr 7890

# macOS / Linux
lsof -i :7890

Once you find the process, either end it or change to a different port in the client settings. While you're at it, check your startup items for two proxy clients fighting each other — keep only one.

Learn to Read the Logs

If it's still crashing after ruling out both of the above, the logs have to do the talking. The main clients on our list (Clash Plus, Clash Verge Rev, FlClash, etc.) all have a log page or an "open log folder" option. Set the log level to debug, reproduce the crash, and look at the last few lines — the last entry before the crash usually points to the culprit module. For errors you don't understand, search the keyword in the FAQ's "Troubleshooting" category, which covers common error messages.

How to Do a Clean Reinstall Properly

1. Back up first: export or copy down your subscription link, and copy your custom rules and config files somewhere safe;
2. Uninstall and clear leftovers: after uninstalling, manually delete the config directory (find its location via the client's "open config folder" option) — leftover broken configs are the #1 reason reinstalling doesn't fix the crash;
3. Reinstall and restore step by step: get it installed and running with an empty config first, then import the subscription, then gradually add back your customizations — verify after each step, and the bad piece will reveal itself;
4. Cross-check with a different client: try another client on the same platform (the Downloads page lists two to four options for each platform, Clash Plus being the top pick). If the same config crashes there too, it's a config problem; if it runs fine, dig deeper into the original client.

Symptom 8: Mobile-Specific Issues (Android / iOS)

Mobile problems follow their own logic: desktop issues are usually about config, while mobile issues are usually about system permissions and background policies. Applying desktop thinking to a phone often leads you the wrong way — hence its own chapter.

Android: Permissions and Background Behavior Are the Two Weak Points

• VPN permission: Android clients rely on VpnService to take over traffic, and the first-launch authorization dialog must be approved. If that permission is later revoked in system settings, or another VPN app grabs the tunnel (the system only allows one active VPN at a time), the client fails silently. Check Settings → Network → VPN to see which one is currently active;
• Battery optimization killing the background app: aggressive power-saving on heavily customized system skins is the biggest cause of "it keeps disconnecting while I'm using it." Add the client to the battery optimization allowlist, allow background running and auto-start, and on some systems, lock it in the recent apps list too;
• Misconfigured per-app proxy: if the client's per-app proxy list (allow / exclude) has the target app excluded, that app naturally bypasses the proxy. If something's off, reset the per-app proxy to default before troubleshooting further;
• Data Saver mode and Private DNS: the system's Data Saver mode restricts background networking, and the system-level Private DNS setting can conflict with the client's DNS. Set it to automatic while troubleshooting.

The Android clients on our list (Clash Plus, Clash Meta for Android, FlClash, Surfboard) are in the Android section of the Downloads page — cross-checking the same subscription against a different client works just as well on mobile.

iOS: It's All About the VPN Configuration

• Installation source: on iOS, just install Clash Plus from the App Store — the link is in the iOS section of the Downloads page;
• VPN configuration conflicts: devices that have installed multiple proxy apps end up with several VPN profiles under Settings → General → VPN & Device Management. Disconnect the old one before switching apps — two profiles fighting over the tunnel is a common cause of "it's on but nothing's flowing" on iOS;
• Brief drops after switching networks: the VPN tunnel has to rebuild when switching between Wi-Fi and cellular, and a few seconds of interruption is normal. If it drops repeatedly and doesn't recover, check whether "connect on demand / auto-reconnect" is enabled in the client;
• The app gets reclaimed in the background: when memory is tight, iOS reclaims background apps — the VPN tunnel usually stays up, but the app's UI needs to reload. Just reopen it; this isn't a bug;
• Subscription update fails: on cellular, check whether the system has blocked the app from using cellular data (per-app toggles under Settings → Cellular).

General Advice for Mobile

A phone's network environment is far messier than a desktop's — Wi-Fi, cellular, carrier DNS, and hotspots all behave differently. If something's intermittent, reproduce it on one fixed network first — don't try to diagnose it while hopping between cell towers on the subway. When a subscription update fails, paste the link into a browser to check reachability (same method as the Subscription Failures chapter) to quickly tell whether it's a link problem or an app problem. Both platforms' power-saving and low-data modes interfere with background networking — turn them all off while troubleshooting.