Clash Troubleshooting Handbook

General diagnostic approach and tools

Clash's data path can be broken into four segments: the app sends a request → the system proxy or TUN hands the traffic to the client → the client matches an outbound based on rules → the node delivers the traffic to its destination. A break in any segment looks the same from the outside — "no internet" — but the cause and the fix are completely different for each. There's really only one core move: figure out which segment the problem is in, then only fix that segment.

Diagnostic order: work from near to far

Always check in this order, and don't skip steps based on a hunch: first confirm the client process is running and the config has loaded (you can see the node list in the UI); then confirm traffic is actually reaching the client (new connection entries appear in the connections panel); then confirm rule matching is behaving as expected (the outbound shown in the connection log is the policy group you expect); only then should you suspect the node itself. Checking in reverse order — jumping straight to swapping nodes or subscriptions — is the most common way to waste time, because when the local path is broken, no node will work anyway.

Logs are your first-hand evidence

Every Clash-family client provides a log panel, and the verbosity is controlled by the config file's log-level field. During troubleshooting, temporarily set it to debug, then switch back to info once resolved — otherwise the log volume gets unwieldy.

Verify the proxy path with one command

Skip the browser and send a request directly through the local mixed port with curl — this is the fastest way to check whether the "client to node" segment is working. A 204 or 200 response means the path is healthy; a hang/timeout means the node is unreachable; connection refused means nothing is listening on the local port.

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

If your mixed port isn't the default 7890, replace it with whatever value mixed-port is set to in your config. This command bypasses the system proxy setting entirely, so its result cleanly separates "system proxy misconfigured" from "node unreachable": if the command succeeds but the browser doesn't, check System proxy not working; if the command also fails, check All nodes timing out.

Narrow the variables: change one thing at a time

When you're not sure what's wrong, run three controlled experiments in order: switch to a different node (rules out a single bad node), switch to Global mode (rules out a rules problem), and temporarily quit other proxy/accelerator/security software (rules out multiple apps fighting over traffic). Change only one variable per test and note the result — after three tests, the problem is usually narrowed down to one specific chapter.

No internet access at all after enabling

Symptom: after enabling the client, no website loads at all (including domestic Chinese sites), or the network works fine again after quitting the client. This category almost always sits in the local path, not the node.

Step 1: confirm the underlying network is fine

Fully quit the client first (quit the process, not just minimize it to the tray), then try opening a Chinese website. If it still won't load, the problem has nothing to do with Clash — fix the local network first. If it loads after quitting but not after enabling, keep going. Watch for one edge case: nothing loads even after quitting the client — this is usually a leftover system proxy setting that wasn't rolled back after an abnormal exit. See the "Leftover proxy settings" section in System proxy not working.

Step 2: confirm traffic is reaching the client

Open the client's Connections panel, refresh a web page, and watch for new connection entries. If entries show up, the system-proxy segment is fine and the problem is further down the chain. If nothing shows up at all, traffic isn't reaching Clash — either the system proxy wasn't actually written, or the app in question ignores the system proxy (typical of command-line tools). Either way, head to System proxy not working.

Step 3: use Global mode as a control

Switch the outbound mode from Rule to Global, pick a node you've previously confirmed works, and refresh. If Global mode gets you online but Rule mode doesn't, the problem is in the rules: most likely a missing rule set is sending too much traffic to the wrong outbound, or the catch-all rule MATCH is pointing to a policy group with no usable nodes. Check the catch-all rule at the end of the config and confirm the group it points to has working nodes:

rules:
  # ...specific rules above...
  - GEOIP,CN,DIRECT      # Direct connection for mainland China IPs
  - MATCH,PROXY          # Everything else goes to the PROXY group (confirm it has usable nodes)

If Global mode still doesn't get you online, rules can be ruled out — the problem is the node or the local port, so head to All nodes timing out.

Step 4: check whether domestic traffic is being wrongly proxied

Another "half-broken" pattern: sites outside China load fine, but Chinese sites are slow or won't load at all. This means domestic traffic is being routed through the node, and the node's route back into China is poor. Check whether your rules include GEOIP,CN,DIRECT and direct-connect rules for common Chinese domains; if the config from your subscription is missing these, add your own DOMAIN-SUFFIX direct-connect entries near the top of the rules section. Rules match top to bottom and stop at the first hit, so order matters — direct-connect rules need to sit above the catch-all MATCH.

All nodes timing out or showing abnormal latency

Symptom: the latency test shows timeout for every node; or nodes show a latency number but the connection never actually goes through. First understand what the latency test actually measures, then figure out which layer the problem is in.

How the latency test works, and its limits

The client's latency test sends one HTTP request through each node to a test URL (commonly http://www.gstatic.com/generate_204) and records how long it takes. It's testing the full path "local machine → node → test server," which means: if everything times out, it's usually not that every node has died — it's more likely that the local-to-node segment is blocked as a whole; individual timeouts are more likely to be a problem with that specific node. Also note that a latency number only reflects the round-trip time of one small request — it's not the same thing as actual download speed, which is covered in Slow speed.

Everything times out: rule out three causes in order

First, the subscription may have expired. Node server details (address, port, password) get rotated by the provider, and if your local config is stuck on old info, everything will fail at once. Manually update the subscription and retest latency; if the update itself errors out, go to Subscription update fails.

Second, the local network may be blocking the node's port. Corporate, school, and hotel networks commonly only allow ports 80/443 through — if the nodes use high, non-standard ports, they'll all fail. To check: switch to your phone's mobile hotspot and test again. If everything works on the hotspot but times out on the original network, that confirms it's a network restriction — favor nodes running on port 443 as a workaround.

Third, system clock drift. Some encryption protocols are time-sensitive; if the local clock is off from real time by more than a certain margin (typically around 90 seconds), handshakes fail across the board and it looks exactly like every node is down. Check whether automatic time sync is enabled, manually correct the clock, and retest. This is the most easily overlooked — and easiest to fix — of the three.

Latency shows a number but the connection won't go through

The latency test uses a small HTTP request, while actual traffic may use UDP or long-lived connections — different channels entirely. A typical case: web pages load but voice/video calls don't connect — the node doesn't support UDP forwarding. This is a node capability issue and can't be fixed on the client side; switch to a node explicitly labeled as supporting UDP.

Let auto-selection handle failover for you

Rather than manually switching nodes every time one fails, use a url-test-type policy group to have the client automatically pick the currently-fastest node and fail over automatically when one goes down:

proxy-groups:
  - name: Auto Select
    type: url-test
    proxies: [NodeA, NodeB, NodeC]
    url: http://www.gstatic.com/generate_204
    interval: 300        # Re-test every 300 seconds
    tolerance: 50        # Don't switch if the latency difference is under 50ms, to avoid rapid flip-flopping

Subscription update fails

Symptom: clicking "update subscription" throws an error, or it hangs with no response. Updating a subscription is essentially the client sending one HTTP request to your subscription URL and parsing the response into a config file, so troubleshooting splits into two buckets: "request failed" and "parsing failed."

Read the error message first: common errors

Request path issues: bypass the client to verify

Request the subscription URL directly from the command line, removing the client as a variable:

curl -v -o sub.yaml "https://your-subscription-url"

If this command downloads fine but the client's update still fails, it's most likely because the client's update request is going through a dead proxy: many clients default to "update subscription through proxy," and when every node is down, you end up in a deadlock — updating the subscription requires a working node, and getting a working node requires updating the subscription. The fix is to temporarily switch to "update via direct connection" in the client's subscription settings, update successfully, then switch back once nodes are working again. The same applies the very first time you import a subscription — there are no working nodes yet, so direct requests must be allowed.

If the command also fails to download, the subscription server itself is unreachable on your current network, unrelated to the client: try a different network (like a mobile hotspot), or contact the provider to confirm whether the subscription URL has changed.

Parsing issues: the response isn't a config

When you get a YAML parse error, open the sub.yaml saved in the previous step with a text editor: if it's a chunk of HTML (an error page or a verification page), the subscription server treated the request as a browser visit, or the subscription has expired; if it's a Base64 blob or another encoded node list rather than full YAML, the subscription format is meant for a different core — choose the "Clash format" option when retrieving the subscription, or use a format-conversion URL provided by your provider.

The User-Agent is being treated differently by the server

Some subscription services return different formats — or reject unfamiliar UAs outright — based on the request's User-Agent. Clients like Clash Verge Rev and FlClash let you customize the UA used for subscription requests; when you hit a 403 or a wrong format, try setting the UA to clash or whatever value your provider specifies — that usually resolves it immediately.

Connected, but speed is slow

Symptom: the network works, but pages load slowly, video quality won't go up, or download speed is far below expectations. Speed problems have the most variables, so establish a baseline first before attributing the cause.

Step 1: establish a local bandwidth baseline

Turn off the proxy and run a direct-connection speed test first, and note the number. Speed through the proxy can never exceed this ceiling — if your direct connection is only 20 Mbps, getting 15 Mbps through the proxy is already normal overhead and not worth chasing. Compare different nodes' actual speed against this baseline.

Step 2: dispel the "latency = speed" myth

The latency test reflects small-packet round-trip time; actual speed depends on the node's bandwidth and how many users are sharing it. A 60ms node can absolutely be much slower than a 200ms node — the former might be a crowded shared line, the latter an idle high-bandwidth one. Picking nodes by latency only makes sense for latency-sensitive use cases (like remote terminals); for downloads and video, test actual throughput instead, by downloading a large file through the node and watching the sustained rate.

Step 3: check whether domestic traffic is detouring through the node

When rules are missing, traffic to Chinese sites goes out of the country and back in, and speed craters while latency doubles. Open the connections panel, visit a Chinese website, and check whether that connection's outbound is DIRECT. If it isn't, add direct-connect rules:

rules:
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Note that the GEOIP rule relies on a local GeoIP database, which the client generally downloads automatically; if the log reports a missing database, trigger a database update manually in the client's settings.

Step 4: peak hours and line quality

Slowdowns in the evening that clear up late at night are the classic sign of congestion at the international gateway — a line-quality issue, not a config issue: switch to a node in a different location (a nearby HK/Japan/Singapore node is usually better than a far-away one), or use whichever line your provider flags as premium. If every node is slow all day, check whether something in the background (a download manager, etc.) is saturating your upload, and whether the router has a rate limit or QoS policy enabled.

Step 5: client and core-level factors

Actively maintained clients (see the Client Comparison) run newer cores with better support for newer protocols and multiplexing; staying on an unmaintained, discontinued client will gradually cost you both speed and compatibility. Also, TUN mode and system-proxy mode have different throughput characteristics on different systems — if you're speed-sensitive, test both and use whichever performs better.

DNS-related issues

Symptom: some sites won't load while others work fine; a domain resolves to a clearly wrong IP; all domains fail to resolve after enabling TUN; or some apps show an IP starting with 198.18.x.x. All of these point to the DNS configuration.

Understanding enhanced-mode: fake-ip vs. redir-host

Clash's DNS module works in two modes. In fake-ip mode, the client first hands out a fake IP from the 198.18.0.0/16 range for every domain, letting the app establish a connection immediately, and defers the real resolution until the traffic actually goes outbound — the upside is zero-wait resolution and full domain info preserved for rule matching; the downside is that some programs cache or report this fake IP, which can be confusing. redir-host mode, on the other hand, resolves the real IP up front. Mainstream configs default to fake-ip and generally don't need changing; seeing a 198.18.x.x address by itself is not a bug.

A ready-to-use dns block template

dns:
  enable: true
  listen: 0.0.0.0:53          # Recommended to listen on port 53 in TUN mode
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"                  # LAN hostnames should not use fake-ip
    - "+.stun.*.*"             # STUN probing needs a real IP
    - "time.*.com"             # Time-sync services
  nameserver:                  # Regular resolution: fast, stable domestic DoH
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:                    # Fallback resolution: DoH outside China, guards against tampering
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN             # Trust the nameserver result if it resolves to a mainland China IP; otherwise use fallback

What each field does: nameserver handles everyday resolution — using DoH inside mainland China keeps domestic domain lookups fast and accurate; fallback is a second resolution path run in parallel, and its answer is used whenever fallback-filter decides the nameserver result looks suspicious (for example, a domain hosted outside China resolving to an odd result), as a defense against DNS tampering. For a field-by-field breakdown and more configuration patterns, see the blog post "Clash DNS Configuration, Explained Field by Field".

Typical failures and their fixes

A specific site won't load while everything else is fine: search for that domain in the connections panel and check whether its resolution and outbound are what you'd expect; if the domain is being wrongly direct-connected with an abnormal resolution result, adding a proxy rule for it (DOMAIN-SUFFIX,example.com,PROXY) usually fixes it.

All resolution fails after enabling TUN: TUN mode routes the system's DNS requests through the client as well, so the dns block must have enable: true and listen on port 53 (per the template above), otherwise the system's resolution requests have nowhere to go. Check whether "DNS hijacking" is enabled in the client's TUN settings, or if you're editing the config directly, confirm listen: 0.0.0.0:53 is present.

LAN devices (printers, NAS) behave oddly: caused by LAN hostnames being taken over by fake-ip — add the relevant domain pattern to fake-ip-filter, like *.lan in the template.

Games or call apps behave oddly: these apps often use STUN to probe their public address, and fake-ip interferes with that probing — the +.stun.*.*-style filter entry in the template exists for exactly this; add whatever probing domain the specific app uses.

System proxy not taking effect

Symptom: the client is running fine and the curl verification command from Chapter 1 works, but the browser or certain apps just won't route through Clash; or the system remains in a proxied state after quitting the client.

Confirm whether the system proxy was actually written

What the client's "system proxy" switch actually does is write 127.0.0.1:7890 into the OS's proxy settings. After flipping the switch, go check it yourself in the system:

If the switch is on but nothing was written to the system: check whether another piece of software (a browser proxy extension, an accelerator, a second proxy client) is overriding the setting; on macOS, also note that the proxy is written to the "currently active network service" — with multiple network interfaces connected, it may have been written to the wrong one.

Apps that ignore the system proxy: environment variables and TUN

The system proxy is really just a "suggestion" — apps are free to ignore it. Command-line tools (git, package managers, various SDKs) mostly ignore the system proxy by default and need explicit environment variables:

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

This only applies to the current terminal session, which is fine for one-off use; for something more permanent, add it to your shell's config file. For apps that neither respect the system proxy nor offer a proxy setting at all, the real fix is TUN mode: the client creates a virtual network adapter and takes over all traffic at the network layer, which no app can bypass. To enable it via config file:

tun:
  enable: true
  stack: system          # Try gvisor for comparison if you hit compatibility issues
  auto-route: true       # Automatically take over routing
  auto-detect-interface: true

Note that TUN requires admin/root privileges, and requires the DNS block to be configured correctly per the template in the previous chapter; mainstream clients (Clash Plus, Clash Verge Rev, FlClash) all provide a TUN toggle and the necessary permission prompts right in the settings UI — prefer that over hand-editing the config.

Leftover proxy settings: still no internet after quitting

When the client is force-killed (a crash, ending the process in Task Manager, a power cut), it doesn't get a chance to restore the system proxy setting, so after restarting, the browser is still trying to connect to a 127.0.0.1:7890 that no longer exists — which looks like "nothing loads at all." The fix: go to the system proxy settings from the table above and manually turn the proxy off, or just start the client again and quit it normally so it cleans up the setting itself. Getting into the habit of always quitting from the tray menu normally will prevent this altogether.

Startup failures and client crashes

Symptom: double-clicking does nothing, the app crashes immediately on launch, the core keeps restarting, or the log stalls on a specific error. Errors in this category are usually very specific, so find the exact wording in the log first.

Port already in use: bind: address already in use

If the startup log shows bind: address already in use, it means the port the config wants to listen on (commonly 7890/7891/9090) is already taken by another process — possibly a previous core instance that didn't shut down cleanly, or a different piece of software entirely. Locator commands for each platform:

If the culprit is a leftover old core process, just end it. If it's some other app that's always running, it's usually easier to change your own port — pick a non-conflicting port in the config:

mixed-port: 7893           # Mixed port shared by HTTP and SOCKS5
external-controller: 127.0.0.1:9097   # Move the control API port out of the way too

After changing the port, remember to update the port number in your system proxy settings and environment variables too. For the full step-by-step, see the blog post "What to Do When Clash Reports Port Already in Use".

Config file syntax errors

An error like yaml: line N: in the log means there's a syntax problem near line N of the config file. YAML is extremely picky about formatting; three of the most common mistakes are: using Tab indentation (must use spaces), missing a space after a colon (port:7890 is wrong, port: 7890 is right), and unquoted strings containing special characters (node names with @, #, etc. need to be wrapped in quotes). If you hand-edited the config, check each line against the error line number one by one; if the error is in a config pushed by a subscription, try re-updating the subscription to overwrite your local edits first.

Insufficient permissions

Enabling TUN or listening on a low-numbered port (like DNS's port 53) requires elevated privileges: on Windows, right-click to run as administrator, or use the client's service-mode option; on macOS, follow the client's prompt to grant authorization; on Linux, grant the core binary the necessary capabilities (setcap cap_net_admin,cap_net_bind_service=+ep) or run it as a systemd service. An operation not permitted error in the log falls into this category.

Clean reinstall: the last resort

If crashes keep happening and the logs give no clear lead, do a clean reinstall: back up your subscription URL → uninstall the client → manually delete the leftover config directory (each client's settings page has an "open config directory" entry showing where its data lives) → reinstall the currently maintained version from the Download page → re-import your subscription. If you don't delete the old config directory, reinstalling is often equivalent to not reinstalling at all, and the problem will come right back. If you're still on a discontinued client (like Clash for Windows) and it keeps crashing, just switch to an actively maintained one — see the Client Comparison for migration guidance.

Mobile-specific (Android / iOS)

Mobile operating systems are far stricter about background processes and network interfaces than desktop systems, and a lot of issues you'd "never see on desktop" trace back to this. This chapter is split by platform.

Android: VPN authorization and background survival

The Clash client on Android (Clash Plus is recommended; others are listed in the Android section of the Download page) takes over traffic through the system's VPN interface, and the first launch must approve the system's "create VPN connection" prompt. If you accidentally decline it, the client just spins uselessly, and you won't be able to re-trigger it under Settings → Apps → that app → Permissions — you need to go into the system's "VPN" settings and initiate the connection authorization again. No key icon in the status bar means the VPN tunnel was never established.

The second major category of issues is getting killed in the background: the network drops after the screen has been locked a while, and reopening the app shows the core has stopped — that's the system's battery optimization cleaning up the process. Fix it with three settings: mark the app as "unrestricted / allow background activity" in the battery settings; lock the app in the recent-apps list; and on customized Android skins (MIUI, ColorOS, HarmonyOS, etc.) also allow it in their respective "autostart management" screens. Doing all three noticeably improves background survival.

On top of that, Android clients generally support "per-app proxying": route only specific apps through the proxy, or exclude specific apps. If a banking app is sensitive to being proxied, just add it to the exclusion list — no need to turn off the proxy device-wide.

Android: config and subscription quirks

Updating subscriptions on mobile is subject to the same "update-through-proxy" deadlock covered in Subscription update fails; if you're mindful of data usage, watch your auto-update interval — the subscription file itself is small, but frequent background latency tests do add up to a steady trickle of small requests. For ways to keep configs in sync across multiple devices, see the blog post "Comparing Ways to Sync Clash Config Across Multiple Devices".

iOS: install channel and common issues

On iOS, install Clash Plus through the App Store (official site clashplus.io; store link is in the iOS section of the Download page). After installing, the first launch also requires approving the system prompt to add a VPN configuration, which then shows up under Settings → General → VPN & Device Management. There are two common issues: first, the toggle flips back off immediately after being turned on — usually because no subscription has been imported, or the config has no usable nodes; confirm in-app that the node list is non-empty and the latency test returns results before enabling the connection. Second, a brief connection drop after switching between Wi-Fi and cellular — this is the normal process of the VPN tunnel being rebuilt during a system network switch, and it recovers on its own within seconds; if it doesn't recover, manually reconnect in-app.

iOS only allows one active VPN configuration at a time, so if you have multiple proxy-type apps installed, them displacing each other is expected — just keep whichever one you actually use. Also, when an iOS app is reclaimed from the background by the system, the VPN tunnel is maintained by the system's network extension and this normally doesn't affect the connection; if disconnects happen frequently, check your subscription validity and node quality first, rather than repeatedly reinstalling the app.

General mobile self-check list

1. Is there a VPN icon in the status bar (the key icon on Android / the "VPN" indicator on iOS)? If not, the tunnel was never established — go back to the authorization step.
2. Does the in-app latency test find any usable node? If everything times out, follow All nodes timing out — test on both cellular and Wi-Fi separately to rule out a network-environment factor.
3. Did the subscription's most recent update succeed? If it failed, follow Subscription update fails.
4. Does the problem only happen in a specific app? If so, look at the per-app proxy list and that app's own networking behavior.

Still not resolved? Where to go from here

If you've worked through this whole page and still haven't pinned it down, there are usually three remaining possibilities. First, the issue may be on the service side: only the provider can confirm the state of the subscription's nodes, lines, or quota — bring the evidence you gathered while troubleshooting (the exact error message, which nodes worked and which didn't, when it started) when you reach out; that's far more effective than just saying "it doesn't work." Second, the issue may be in the client implementation: cross-check the same subscription on a different, actively maintained client, and if everything works fine there, follow the Client Comparison to migrate — no need to keep fighting the old one. Third, the issue may be a gap in some basic step: go back to the Setup Handbook and work through the main flow again — a huge share of "weird bugs I spent forever on" turn out to be one basic toggle that was never switched on.

Finally: keep the client and subscription updated, prefer actively maintained clients, and hand your everyday outbound selection over to url-test auto-selection — these three habits alone prevent more than 70% of the issues on this page. The real value of a tool is being stable and predictable — set it up once and let it work quietly in the background; that's the actual end goal of troubleshooting.