#Clash Troubleshooting Guide: Symptom-Based Chapters

No Internet After Turning Clash On: Isolate the Layer First

"Clash is on but nothing loads" is the most common and vaguest symptom. It can come from four completely different layers: the local network itself is down, the client isn't actually listening, the system isn't handing traffic to the client, or traffic reaches the core but a rule sends it to a dead exit. The first principle of diagnosis is narrowing down layer by layer — don't jump straight to reinstalling the client or swapping subscriptions.

Step 1: Confirm the direct connection works

Turn off the client's system proxy or TUN mode first, then visit a site directly (for example, your ISP's homepage). If it still doesn't load with the proxy off, the problem is your router, cable, or ISP — nothing to do with Clash, and you should fix the basic network first. If direct access works but everything breaks once the proxy is on, keep going.

Step 2: Confirm the port is listening

Clash-family clients open a mixed proxy port (accepting both HTTP and SOCKS) on 7890 by default. Confirm the port is actually bound with:

# Windows (PowerShell or CMD)
netstat -ano | findstr 7890

# macOS / Linux
lsof -i :7890

If there's no output at all, the core failed to start — usually a config parsing error or a port already taken by another program; jump straight to the Client Crashes chapter. If the port is listening, test connectivity through the proxy with curl:

curl -x http://127.0.0.1:7890 -sS -o /dev/null -w "%{http_code}\n" \
  https://www.gstatic.com/generate_204

A 204 means the "core + current node" path works, and the problem is at the system proxy layer — see System Proxy Not Working. A timeout or error means the exit itself is broken — see Node Timeout.

Step 3: Rule out rule mis-routing

Switch the client to Global mode and try again. Global mode skips all routing rules and sends traffic straight to whichever node you've selected: if Global works but Rule mode doesn't, a rule is sending the target domain to a broken policy group, or the fallback MATCH rule points to DIRECT. The routing logic differences between the three modes are covered in this note: Rule, Global, and Direct — Which Proxy Mode Should You Use?

Node Timeout: One Node vs. All Nodes

The latency number in the client comes from timing an HTTP request to a test URL, commonly https://www.gstatic.com/generate_204. A timeout means that probe got no response within the time limit — the cause could be the node server, the transport protocol, local network interference with a specific port, or the test URL itself acting up. Before diagnosing, answer one question first: is it one node timing out, or every node?

All nodes time out at once

If every node turns red at once, you can basically rule out the nodes themselves — check three things first. First, is the direct connection fine — go back to step 1 of the previous chapter. Second, is your system clock accurate: most encrypted protocols are sensitive to time drift, and a manually changed time zone or a drifting VM clock can break every handshake; set the system time to auto-sync and retest. Third, has the subscription as a whole expired or been banned server-side — log into your subscription provider's dashboard to check traffic and expiry, and if needed re-pull the config following the Subscription Failures chapter.

A single node times out

A single timing-out node is most often just a server under load or an unstable route — switch to another node in the same region. If a particular node is flaky over time, use a url-test policy group to let the core auto-select whichever node currently works, like this:

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - HK-01
      - JP-01
      - SG-01

interval is the retest interval in seconds; tolerance means the latency gap between the old and new node must exceed this many milliseconds before switching, which avoids flip-flopping between two nodes with similar latency. The Setup Guide and related articles cover policy group design in more depth.

Latency looks fine but it still doesn't work

A latency test only confirms "a connection can be established" — it says nothing about bandwidth, and nothing about UDP. Games and voice calls rely on UDP forwarding; if the protocol or the server doesn't support UDP, you'll see "latency is green, but the game drops" — this is a subscription-provider issue to confirm, not something the client can fix on its own. Also, the latency number only reflects "you to the node" — when the segment from the node to the target site is congested, you can still get low latency and a page that won't load; switching to a different exit region usually fixes it immediately.

Subscription Update Failures: Read the Error Before Deciding Direct vs. Proxy

A subscription is essentially an HTTP(S) address that returns a YAML config or a convertible node list. When an update fails, the client usually shows an error, and different errors call for completely different fixes — don't just mash the update button repeatedly.

Manually verify the subscription URL

When the client's error message is too vague, pull the subscription directly with curl to isolate the client from the equation:

# Fetch directly
curl -sS -o sub.yaml -w "%{http_code}\n" "your-subscription-url"

# Fetch through the local proxy
curl -x http://127.0.0.1:7890 -sS -o sub.yaml -w "%{http_code}\n" "your-subscription-url"

If it returns 200 and sub.yaml shows a node list starting with proxies:, the subscription itself is healthy and the issue is in the client's settings (commonly a User-Agent rejected by the server — try a different client identifier). If one command works and the other doesn't, the subscription domain is being interfered with on your current network — just stick to whichever path works; most clients have a "use proxy to update" toggle in the subscription editor.

Update succeeds but nodes don't change

Some clients cache subscriptions locally, so check the config's last-updated timestamp after updating. Also note: if you manually edited routing rules in the config file and then hit update, your changes get overwritten by whatever the server sends — for long-term custom rules, use the client's "config enhancement / merge script" feature instead of editing the downloaded subscription file directly.

Slow Speed: Find Which Segment Is the Bottleneck

"Slow" is a bucket-effect problem across the whole chain: your local bandwidth cap, the route quality from you to the node, the node server's own bandwidth, the route from the node to the target site, and the overhead of the encryption protocol itself. Diagnosing slowness is mainly about figuring out which segment is slow, not blindly switching nodes.

Establish a baseline

Turn off the proxy and test your raw local speed, note the number; then turn the proxy on, switch to Global, pick the lowest-latency node, and test again. The gap between the two numbers is "proxy chain overhead + node bottleneck" combined. If the raw speed itself is only a few Mbps, no node will save you; if raw speed is high but drops to a tenth or less with the proxy on, keep narrowing further.

Common causes and fixes

Send traffic that shouldn't be proxied straight through

A hidden cause of slowness is often poor routing: system updates, game downloads, cloud sync don't need to detour through the exit. In Rule mode, confirm those domains hit DIRECT, and add manual rules if needed. Whether geo-based rules (GEOIP, GEOSITE) match correctly depends on how fresh the local database is — see this note for how to update it: How to Update GeoIP and GeoSite Databases.

DNS Issues: Pollution, Leaks, and the Fake-IP Trade-off

A good chunk of "rules don't work," "a specific site won't load," and "first load is slow" issues trace back to DNS. The Clash core has its own DNS module, and understanding its two enhanced modes and the layered nameserver design resolves most of these hard-to-pin-down problems.

Recognizing the symptoms

Classic DNS pollution looks like: the domain resolves to an IP, but that IP simply can't be reached, or the resolved address clearly doesn't belong to the target site. A DNS misconfiguration instead shows up as domain-based rules (DOMAIN-SUFFIX, etc.) matching fine but GEOIP rules misbehaving, or the old address still being used after switching nodes. Compare local resolution against a public DoH resolver with nslookup or dig to quickly confirm whether you're being tampered with.

A recommended DNS config skeleton

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"
    - "time.windows.com"
    - "+.ntp.org"
  nameserver:
    - https://223.5.5.5/dns-query
    - https://doh.pub/dns-query

enhanced-mode: fake-ip lets the core answer queries instantly with an address from a reserved range, skipping the wait for real resolution and guaranteeing precise domain-rule matching — it's also the default mode for most clients. For the full workflow, how it differs from redir-host, and which scenarios need to exclude it, see this breakdown: How Fake-IP DNS Mode Works.

Common Fake-IP pitfalls and the exclusion list

Programs that need a real IP will break under Fake-IP: LAN device discovery, NTP time sync, some game launchers, and P2P apps that need incoming connections. The symptom is these programs getting a 198.18.x.x address and misbehaving. The fix isn't to disable Fake-IP — add the relevant domains to fake-ip-filter so they get real resolution instead. If the old fake address is still cached by the system after the config change, flush it with ipconfig /flushdns on Windows or sudo dscacheutil -flushcache on macOS.

System Proxy Not Working: Some Traffic Just Ignores It

A system proxy is really just an operating-system-level suggestion — "the HTTP/SOCKS proxy is at 127.0.0.1:7890" — and it really is a suggestion, not a mandate. Browsers and most modern apps respect it, but command-line tools, some legacy software, and Windows UWP apps ignore it entirely. Once you understand that, half the "not working" cases already have an answer: the proxy isn't broken, that particular program just never planned to use it. For a comparison of how the two traffic-takeover mechanisms work, read: TUN Mode vs. System Proxy: What's the Difference?

Windows: UWP loopback restriction

Microsoft Store apps (UWP) are blocked by default from reaching the local loopback address — so even if the system proxy points to 127.0.0.1, traffic from Store apps never reaches Clash. Most Windows clients have a built-in "UWP loopback helper / Loopback tool" — just check the box for the target app. You can also allow it manually with the built-in command, for example allowing the Microsoft Store itself:

CheckNetIsolation.exe LoopbackExempt -a -n="Microsoft.WindowsStore_8wekyb3d8bbwe"

# View the current exemption list
CheckNetIsolation.exe LoopbackExempt -s

Command line and dev tools

Terminal tools like git, pip, npm, and curl don't read system proxy settings — you need to set environment variables explicitly, or switch to TUN mode for full takeover:

# macOS / Linux (applies to the current session)
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

# Windows PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7890"; $env:HTTP_PROXY="http://127.0.0.1:7890"

Proxy settings overwritten or never written

After toggling "system proxy," check the OS's proxy settings page directly: Windows under Settings → Network & Internet → Proxy, macOS under System Settings → Network → [current network service] → Details → Proxies. If the address isn't 127.0.0.1:7890, common causes include: another proxy tool (or a leftover driver) repeatedly overwriting the setting, or on macOS the actually-active network service isn't the one that got written to (e.g. it wrote to Wi-Fi but you're actually on Ethernet). Kill the conflicting software, confirm the network service order, and toggle it back on. The way to sidestep this layer entirely is TUN mode, which takes over all traffic at the network layer via a virtual adapter — the trade-off is needing admin rights and watching out for compatibility with other virtual-adapter software.

Client Crashes and Startup Failures: Read the Logs

"Nothing happens when I click it," "it crashes on launch," and "the connection just drops mid-session" almost always leave a clear trail in the logs — reinstalling blindly has a much lower success rate than reading the log first. Every client has an "open logs / open app folder" entry in settings or the tray menu — set the log level to info or debug and reproduce the issue before diagnosing.

Exits immediately on launch: check config first, then the port

The most common startup failure is a config parsing error — YAML is extremely sensitive to indentation and the space after a colon, and a manual edit missing one space can break the whole config. The log will give you a specific line number to fix; if the change was substantial, switch back to an unmodified subscription config first to check whether the client itself is fine, separating a "config problem" from a "program problem." The second most common cause is a port conflict: 7890 or 9090 (the external controller port) taken by another program — the log will show something like bind: address already in use; use netstat/lsof as shown above to find the culprit, or change to a different port in the config.

Connection drops or crashes while running

A sudden drop in TUN mode usually points to a conflict between the virtual adapter driver and other network software (a VM, another proxy tool, some security software) — the log usually shows an adapter creation or route write failure nearby. Networking not recovering after sleep/wake is an old, cross-platform issue — toggling TUN or the system proxy off and back on usually fixes it. Memory climbing until the OS kills the process is mostly seen with configs that have huge node counts or too many rule sets — trimming the subscription and cutting unnecessary rule-set subscriptions helps a lot.

Resetting or switching clients

Once you've confirmed it's a program issue, uninstalling and manually clearing leftover app data before reinstalling works better than an over-the-top install (back up your subscription URL first). The same subscription works across different clients, so if one client doesn't play well with your system, switching is a cheap thing to try. See Client Comparison for the recommended order per platform, and grab installers from the Get the Client page — Clash Plus is the default recommendation on every platform.

Mobile Devices: Android and iOS Each Have Their Own Pitfalls

Mobile failure patterns differ from desktop: the OS manages background processes and VPN tunnels far more aggressively, so the problem is often OS policy, not the config. This chapter covers each platform separately.

Android: VPN permission and staying alive in the background

Android clients take over traffic through the system VPN interface — the first launch must be approved via the system's "create VPN connection" prompt. If you tapped decline back then, you'll now see "tap start, nothing happens" — go to the system's VPN settings and reauthorize the app. The second big category is getting killed in the background: battery optimization on custom Android skins tends to kill long-running VPN services, showing up as "it disconnects after a while" or "stops working after the screen's been locked for some time." The fix is to whitelist the client from battery optimization, allow autostart and background running, and lock it in recent tasks. Also check the "Always-on VPN" and "Block connections without VPN" options: the former improves survival, but the latter will cut off all internet access if the client exits abnormally — check the state of both toggles when diagnosing a disconnection. Misconfigured per-app proxying (Access Control) is also often mistaken for a bug — if only specific apps aren't going through the proxy, check whether they're excluded from the list first.

iOS: Get it from the App Store, watch the config size

iOS takes over traffic via a Network Extension, and the OS enforces a tight memory limit on this kind of extension in the background. If a subscription has too many nodes or a huge rule-set attached, the extension process can be killed by the system for exceeding the limit, showing up as "the connection toggle flips itself back off." The fix is to trim the config: ask your provider for a lighter subscription with fewer nodes, or remove rules you don't need in the client. iOS clients are distributed through the App Store — Clash Plus (clashplus.io) is the default recommendation; see the iOS section of the download page for the store link and instructions. Brief disconnects when switching between Wi-Fi and cellular are normal while the extension rebuilds its tunnel — if it doesn't recover in a few seconds, manually toggle it off and on.

Another option: let a computer proxy for mobile devices

For TVs, game consoles, or any device where installing a client isn't practical, run Clash on one computer and share it across the network: enable allow-lan, then point the other devices' proxy settings at the computer's LAN IP and mixed port. Full steps (including bind-address values and firewall rules) are in this note: Sharing a Clash Proxy Over the Local Network.

Still Stuck? What to Try Next

If you've gone through the relevant chapter and the issue persists, try this order: first, set the log level to debug and reproduce the issue once — the raw error text in the log is usually far more informative than the symptom itself; second, run a minimal test — swap in a clean config, try a different client, try a different network, changing one variable at a time to box in the actual cause; third, skim the FAQ page by category — a lot of small issues (autostart, config file location, mode switch not taking effect) have direct answers there. If you're not confident with the basics, walk through the Setup Guide again — a lot of "hard problems" are really just a skipped step.