Clash Troubleshooting Manual

No Internet Access: Everything Goes Offline When the Proxy Is On

Definition: with the proxy on, no site is reachable at all; turning the proxy off restores connectivity immediately. This class of failure means traffic is indeed reaching Clash, but isn't being sent out correctly. Work through the steps below in order.

1.1 Distinguish "everything's broken" from "some things aren't"

Test three kinds of sites: a site in mainland China, a site outside China, and a direct IP address (like a router admin page at 192.168.x.1). Only if all three fail does this chapter apply; if only sites outside China fail, go to DOC-02 to check nodes; if only some sites fail or redirect oddly, go to DOC-05 to check DNS and rules. This step takes ten seconds and saves you from chasing the wrong lead later.

1.2 Check proxy mode and outbound selection

Confirm the current mode. In Rule mode, if the config is missing a catch-all MATCH rule, unmatched traffic may get dropped; in Global mode, if the selected outbound is a dead node, all traffic fails; in Direct mode with the system proxy on, traffic loops through the local machine before going direct, which usually doesn't cause a full outage, but a misconfiguration can create a loop. Fix: switch to Global mode, manually pick a node with normal latency, and see if it recovers. If it does, the problem is in your rules or policy groups — go back to Rule mode and check section by section. If it doesn't, keep reading.

1.3 Check the local listening port

By default, Clash listens on port 7890 on the local machine (the mixed port). If that port isn't up, the system proxy is pointing at an empty address, which shows up as a total outage. Confirm listening status with:

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

# macOS / Linux
lsof -i :7890

No output means the core failed to bind: check the mixed-port or port field in your config, then check the client log for a bind failure (commonly the port is already taken by another program — see the port-conflict section under DOC-07). Output present but the PID isn't Clash's process means the port is occupied — change the port in your config, or terminate the process holding it.

1.4 Bypass the browser and verify the link with curl

Browser caching, extensions, and DoH settings can all skew your judgment. Use the command line to hit a lightweight probe endpoint straight through the local proxy:

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

A response of HTTP/2 204 or HTTP/1.1 204 means the full chain "local machine → Clash → node → target" is working, and the problem lies in the browser or the system-proxy layer — go to DOC-06. A timeout or connection reset means the node side is unreachable — go to DOC-02.

1.5 Check the runtime log

Set the log level to info or debug, reproduce the failed request, and watch the output. Three common patterns:

• dial tcp ... i/o timeout: the connection to the node server timed out — the node is unreachable, go to DOC-02.
• EOF or connection reset: the connection was established then cut off, usually a protocol parameter mismatch on the node side or link interference — switch nodes or contact your subscription provider.
• no such rule / proxy not found: a rule in the config references a policy group name that doesn't exist — this is a config error; re-update your subscription or fix the field you edited manually.

Node Timeouts: Latency Tests Fail Entirely or Partially

Definition: running a latency test in the client's node list returns timeout, -1, or blank results. One thing to clarify first: a latency test measures "total time to reach a specific test URL through that node" — a failed test doesn't necessarily mean the node is dead; the test URL itself might be unreachable.

2.1 Four common causes when everything times out

1. The subscription has expired or run out of data. Log into your provider's user panel and check the account status. This is the single most common cause of a total timeout — check it before suspecting the software.
2. The local network itself is down. Turn off the proxy and try loading any site in mainland China to confirm basic connectivity. If the base network is down, every node will time out.
3. The test URL is blocked by the local network. Some clients' default test address is unreachable on certain networks, making usable nodes show up as "all red." Change the test address to https://www.gstatic.com/generate_204 or http://cp.cloudflare.com/generate_204 and retest.
4. System clock drift. Some encryption protocols are time-sensitive; if the local clock is off from real time by more than a certain margin, the handshake fails. Turn on automatic time sync and retest.

2.2 Partial timeouts: what's normal and where to draw the line

A subscription typically includes dozens of nodes, and the occasional timeout on a handful of them at certain times is normal — caused by server maintenance, line fluctuations, or shifts in regional network restrictions. Handling guidelines:

• All nodes in one region time out while others are fine — that region's line is down; switch regions and wait for the provider to fix it.
• Random, sporadic timeouts — no action needed; a policy group using the url-test type will auto-select a working node.
• The same few nodes consistently time out over a long period — report it to your provider, or exclude them in your config.

2.3 Have policy groups auto-avoid dead nodes

A policy group with manually selected nodes won't switch automatically when a node fails. Switching common policy groups to an auto-speed-test type noticeably reduces the "it just dropped" feeling. Example:

proxy-groups:
  - name: "Auto Select"
    type: url-test
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 60
    proxies:
      - "Node A"
      - "Node B"
      - "Node C"

Field notes: interval is the retest interval in seconds — 120 or higher is recommended, since overly frequent testing generates extra requests; tolerance is the tolerance margin in milliseconds — a new node's latency must be lower than the current one by more than this margin before switching, which avoids flip-flopping between two nodes with similar latency.

2.4 Reading latency numbers correctly

A latency test runs a complete HTTP request, so the number is affected by the node's physical distance, protocol overhead, and the test address's location, all three at once. Rule of thumb: nearby Asian nodes typically run tens to a bit over a hundred milliseconds; European/American nodes in the 200–400ms range are normal. Low latency only means a fast handshake — it says nothing about bandwidth; for download-speed issues, go to DOC-04.

Subscription Failure: Import Errors and Update Failures

Definition: pasting a subscription link produces an import error, or updating an existing subscription fails. A subscription is essentially a remote config file fetched over HTTP, so the diagnostic approach is the same as troubleshooting "a URL won't open": confirm the link itself, then the network path, then the content format.

3.1 Confirm the link itself is valid

1. Check the link is complete. Subscription links are usually long and contain a token parameter, and copying from chat apps can truncate them or introduce stray line breaks or spaces. Re-copy it fresh from the provider's user panel rather than passing it through multiple hops.
2. Confirm the link type. Clash-family clients need a Clash-format (YAML) subscription; some providers issue different links for different clients, and grabbing the wrong format produces a "parse failed" error. Most providers support appending a parameter to the link to specify the format — check your provider's documentation for details.
3. Open the link directly in a browser. If you see a block of YAML text (starting with fields like proxies:, port:, etc.), the link and content are both fine and the problem is on the client side; a 404 or error page means the link has expired — ask the provider to reissue it.

3.2 Handling failures at the fetch stage

If the link is valid but the client's update times out, the subscription server itself may sit on a network path that's being interfered with. Two approaches:

• Fetch through an existing working node. Clients like Clash Verge Rev offer a "use proxy for update" toggle in subscription settings — this requires at least one already-working config.
• Reproduce the issue from the command line. Use curl to simulate the client's request and see exactly where it fails:

# Direct fetch (swap in your own link; the token below is a placeholder)
curl -I "https://example.com/api/v1/client/subscribe?token=xxxx"

# Fetch through the local proxy
curl -x http://127.0.0.1:7890 -I "https://example.com/api/v1/client/subscribe?token=xxxx"

If the direct fetch fails but the proxied one succeeds, the subscription server is unreachable directly — turn on "use proxy for update." If both fail, the problem is on the server side — wait it out or contact the provider.

3.3 User-Agent restrictions

Some subscription servers return different formats based on the request's User-Agent, or reject unrecognized UAs. If the link opens fine in a browser but the client fails to parse it, try manually setting the UA in the client's subscription settings to clash or clash.meta and retrying. This is especially common right after switching clients, when a subscription suddenly stops working.

3.4 Update failed, but the old config still works

The client caches the last successfully fetched config, so an update failure doesn't stop you from using the existing nodes. So a failed update isn't an immediate connectivity emergency — but note that node addresses in the old config may gradually go stale as the provider rotates them, showing up as fewer and fewer usable nodes over time. Restore update capability as soon as possible using 3.1–3.3 above.

Slow Speed: Connected Fine, but Bandwidth Falls Short

Definition: pages load, video plays, but speed is noticeably below your local broadband capacity or past experience. Speed issues have the most variables to account for, so isolate them layer by layer: local network → node → protocol → rules → destination site.

4.1 Establish a baseline: test direct first, then test through the proxy

Turn off the proxy and run a speed test against a mainland China test server to record your local broadband baseline; then turn the proxy on, pick a node, and run another test against the same target or a test point in the node's region. Proxy speed at half the baseline or better is typically within normal overhead; a much larger gap means keep digging.

4.2 Node-side factors

• Node load. During peak hours (evenings), shared public nodes get crowded and bandwidth gets divided up more thinly. Try a less popular region, or compare off-peak — a clear difference confirms this.
• Line quality. Different nodes within the same subscription can route through international links of very different quality. Actually test your three-to-five go-to nodes and record each one's sustained speed; stick with whichever performs well, rather than picking nodes purely by latency number.
• Multiplier tags. Some providers apply a data-usage multiplier to higher-quality lines, often noted in the node's name — keep an eye out when choosing.

4.3 Client and protocol factors

• Core version. The mihomo core's optimizations for newer protocols and concurrency keep improving, and staying on an old client build can cost you performance. Get the current version from the downloads page; both Clash Plus and Clash Verge Rev ship with the mihomo core built in.
• UDP support. Video calls, gaming, and some streaming rely on UDP. If a node or config doesn't allow UDP through, these use cases degrade or stutter. Check the udp: true field on the relevant proxy in your config, and whether your provider supports UDP forwarding.
• Browser QUIC. Browsers route some sites over HTTP/3 (UDP 443), which can be slower on nodes with poor UDP forwarding. Blocking QUIC to force a fallback to TCP is a common workaround:

rules:
  - AND,((NETWORK,UDP),(DST-PORT,443)),REJECT

4.4 Rule-side factors: confirm traffic is being routed correctly

A hidden cause of slow speed is "traffic that should go direct is going through the proxy instead." A mainland China site routed out to an overseas node and back is inevitably going to be much slower. Check the client's active connections panel and confirm mainland domains hit DIRECT and sites outside China hit a proxy policy group. If your routing rules are misconfigured, see the in-depth article Rule-Based Routing in Practice to correct it.

4.5 Local environment factors

Weak Wi-Fi signal, router bottlenecks, and other devices hogging bandwidth all get misdiagnosed as "the node is slow." Retest over a wired connection or close to the router to rule out local interference. If you're running the core on a router or firewall device, also watch CPU usage — throughput on encrypted traffic is capped by device compute, and low-end hardware topping out around 100Mbps is normal.

DNS Issues: Resolution Errors, Leaks, and Sites That Won't Load

Definition: the network overall works, but some sites won't load, redirect to an error page, or a leak-detection tool reports a DNS leak. DNS is one of the least intuitive categories of Clash failure, because the symptom shows up on "certain websites" while the root cause is at the resolution layer.

5.1 Determine whether it's actually a DNS issue

For a site that won't load: try connecting by IP directly (if the site supports it), or check the client log for a resolved IP that's obviously wrong (e.g. resolving to a reserved address, or one that clearly doesn't belong to the target's provider) — either confirms a resolution problem. Another telltale sign: with the proxy on, a site says "not available in your region" even though the node's region is clearly correct — usually the DNS request went out direct, exposing your real location.

5.2 Understanding fake-ip vs. redir-host

Clash's enhanced-mode has two settings. In fake-ip mode, the core instantly returns a fake address in the 198.18.0.0/16 range for any domain lookup, and the real resolution happens later at the outbound stage — this is fast and inherently resistant to tampering, but a few programs that rely on real IPs (LAN discovery, some game platforms) can misbehave. redir-host mode returns the real resolution result, which is more compatible but leans more heavily on upstream DNS quality. For desktop and mobile, fake-ip is generally recommended, paired with a filter list to exclude LAN domains.

5.3 A ready-to-use dns block

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://120.53.53.53/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

Structure notes: nameserver handles everyday resolution — use a China-based DoH server here for fast, accurate resolution of mainland domains; fallback handles a second lookup for domains suspected of being tampered with — use overseas DoH servers here; fallback-filter decides based on GeoIP — if the resolved result isn't in a CN address range, the fallback result is used instead. For the full mechanics of each field and how tampering happens, see the in-depth article A Complete Guide to Clash DNS Configuration.

5.4 Confirming and fixing a DNS leak

1. Visit a DNS leak test site through the proxy and check which resolver servers are listed. All servers belonging to the node's region is normal; seeing a local ISP's server means a leak.
2. Identify the source. Three common causes: the browser's built-in DoH (a separately configured DNS-over-HTTPS setting that bypasses Clash), UDP port 53 requests bypassing the proxy under system-proxy mode, and IPv6 resolution taking a side path.
3. Fix each one: disable the browser's built-in secure DNS; enable TUN mode so DNS requests get intercepted too (see DOC-06); set ipv6: false in your config, or add complete IPv6 rules.

5.5 Misjudgments from an outdated GeoIP database

The GEOIP,CN,DIRECT rule relies on a local GeoIP database. When that database hasn't been updated in a while, newly assigned address ranges get misjudged, showing up as certain mainland sites wrongly going through the proxy, or certain sites outside China wrongly going direct. Most clients provide a GeoIP/GeoSite database update option in settings — run an update and restart the core. If the update fails, first confirm the current proxy is working, then retry the update through the proxy.

System Proxy Not Working: The Client Is Running, but Traffic Goes Direct

Definition: the client shows it's running fine, node latency is normal, but browser or app traffic isn't actually going through the proxy. The key thing to understand: the "system proxy" is just an operating-system-level setting that applications can choose to honor — or ignore. This shapes the whole framework for this chapter.

6.1 Confirm the system proxy setting was actually written

First confirm the client's "system proxy" toggle is on, then check at the OS level: on Windows, go to Settings → Network & Internet → Proxy and check whether the manual proxy points to 127.0.0.1:7890; on macOS, check System Settings → Network → Details → Proxies for the HTTP/HTTPS proxy entries. If the toggle is on in the client but nothing shows up in the system settings, it's usually insufficient permissions or another proxy tool grabbing the setting first — restart the client, or quit the conflicting software and try again.

6.2 What traffic doesn't naturally follow the system proxy

6.3 Configuring proxies for command-line tools

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

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

# git (global config)
git config --global http.proxy http://127.0.0.1:7890

To verify: run curl -I https://www.gstatic.com/generate_204 and check the client's connections panel for a connection from curl — if it shows up, it's working.

6.4 Using TUN mode instead of the system proxy

TUN mode creates a virtual network interface and takes over all traffic at the system routing layer, without depending on any application's cooperation — it's the fundamental fix for "app doesn't honor the system proxy." Key points for enabling it: on desktop, admin/system-extension permission is required; the first time you enable it, a service component needs to be installed (the client will guide you through it); once enabled, it's best to turn off the system proxy toggle to avoid double-proxying. For the mechanics and platform-specific steps, see the in-depth article How TUN Mode Works and How to Enable It.

6.5 Conflicts with browser extensions and PAC scripts

If the browser has an extension like SwitchyOmega installed, the extension's settings take priority over the system proxy. This shows up as the system proxy being correctly configured while the browser still follows the extension's old rules. Fix: switch the extension to "system proxy" mode, or disable it outright. Likewise, a leftover PAC auto-config script address in the system will override manual settings — when troubleshooting, turn off both "automatically detect settings" and "use a setup script."

Client Crashes: Launch Failures, Crashing, and a Frozen UI

Definition: the client won't launch, exits immediately after launching, the core keeps restarting, or the UI hangs for a long time. Nine times out of ten, this comes down to four causes: config syntax errors, port conflicts, insufficient permissions, or a corrupted install. Check them in order from most to least likely.

7.1 Config file syntax errors

YAML is extremely sensitive to indentation and spacing after colons, and this is the single most common cause of the core failing to start after hand-editing a config. How to spot it: check the client log (Clash Verge Rev's app log, or the log entry in each client's settings) — the core will report an error with a line number, like yaml: line 42: mapping values are not allowed in this context. Fix: correct the indentation at that line, or temporarily switch back to an unmodified subscription config to verify it recovers. Copying a backup before editing your config is the cheapest insurance available.

7.2 Port conflicts

When ports like 7890 (proxy) or 9090 (external controller) are already taken by another program, the core fails to start immediately. Common culprits: another Clash instance that didn't fully exit, other proxy software, or a dev/debug service. Diagnose and fix:

# Windows: find the PID holding port 7890, then look up the process name by PID
netstat -ano | findstr 7890
tasklist | findstr 

# macOS / Linux
lsof -i :7890

Once you've identified the offending process, terminate it, or switch to a different port in the config (and update where the system proxy points to). Don't run multiple Clash-family clients at the same time — uninstall whichever one you're not using.

7.3 Permissions and security software

• Windows: antivirus software can block the core process or delete core files, showing up as "it worked yesterday and won't start today." Add the client's install directory to your allowlist and reinstall. For why the false positives happen and how to fix them, see Windows Setup, Start to Finish (and Common Pitfalls).
• macOS: if it's blocked on first launch, go to System Settings → Privacy & Security to allow it; TUN mode's system extension needs to be approved separately.
• TUN-related crashes: enabling TUN requires admin privileges, and an incomplete service-component install will cause a crash right on launch. Reinstall the service component as an administrator, or first turn off TUN and verify the client itself works fine under system-proxy mode.

7.4 Corrupted installs and leftover conflicts

A failed upgrade or disk issue can corrupt program files. Recovery order: uninstall, manually clean up leftover directories (note: configs and subscriptions are usually stored in a separate user-data directory from the program directory, so cleaning the program directory won't lose your config; for a full reset, also delete the user-data directory), then download and reinstall fresh from the downloads page. If crashes keep happening with no clear log lead, try a different client on the same core to cross-check — for example, if Clash Verge Rev crashes but Clash Plus runs fine, the problem is in that client itself, not your config or network.

Mobile-Specific Issues: Platform Quirks on Android and iOS

Mobile clients (Clash Plus, Clash Meta for Android, and FlClash on Android; Clash Plus on iOS) all take over traffic through the system's VPN interface, so their failure modes look noticeably different from desktop — hence a dedicated chapter.

8.1 Android: VPN Won't Establish

1. Confirm system VPN authorization. The first launch pops up a "connection request" authorization dialog; if you accidentally tap "deny," go to the system's VPN management page, delete that app's VPN profile, and relaunch the client to trigger the prompt again.
2. Check for VPN conflicts. Android only allows one app to hold the VPN channel at a time, so other VPN-type apps (including the "network protection" feature in some security apps) running at the same time will prevent Clash from connecting. Disable the conflicting app and try again.
3. Some custom system profiles (Work Profile, Kids Mode) restrict VPN permission — allow it in the relevant management screen.

8.2 Android: Killed in the Background and Connection Drops

Aggressive battery-saving on Chinese-made custom Android skins is the number one cause of mobile connection drops, showing up as the network cutting out a while after the screen locks, or the notification icon disappearing. Checklist:

• In the system battery settings, set the client to "unrestricted" / "no optimization."
• Lock the client in the recent-apps view (pull down and lock the card) to stop it from being swept away by a one-tap cleanup.
• Keep the client's persistent foreground-service notification on — don't disable it for a tidier notification bar, since it's one of the signals the system uses to judge the process's importance.
• Some systems also require separately allowing "auto-start" and "background pop-up" permissions.

8.3 Android: Per-App Proxy

The "Per-App Proxy" setting in the client lets you specify which apps route through the VPN. Two modes: allowlist (only listed apps use the proxy) and blocklist (listed apps bypass it). If a banking app is sensitive to VPN detection, adding it to the bypass list resolves its risk-control error; conversely, if some app is always going direct, first check whether it's been added to the bypass list. Restart the VPN after changing per-app settings for it to take effect.

8.4 iOS: Using Clash Plus

On iOS, install Clash Plus from the App Store; it runs on the system's Network Extension framework. Platform-specific notes:

• The first launch requires allowing the VPN configuration to be added in the system prompt; if you deny it, go to Settings → General → VPN & Device Management to fix it.
• The system's memory limit for a Network Extension is far lower than for a regular app; a config with an oversized rule set or too many nodes can trigger the system to kill the extension process, showing up as the VPN icon flickering off. Trimming down your subscription size and avoiding overly large rule sets helps.
• VPN is also globally exclusive on iOS — disconnect one proxy app before switching to another.
• A brief drop when switching between Wi-Fi and cellular is a normal part of the system's network-stack handoff and recovers within seconds on its own; if it doesn't recover after a while, manually toggle the connection off and on.

8.5 Mobile Subscription Update Failures

Diagnosing a subscription update error on mobile follows the same steps as DOC-03, with two mobile-specific additions: on cellular, some carriers apply stricter resolution and connection policies to unfamiliar domains, so switching to Wi-Fi and retrying can help isolate that; battery-saving mode restricts background network requests, which doesn't affect a manual update run in the foreground, but can mean the "auto-update subscription" task silently stops running for a long time, letting nodes quietly expire — if a batch of nodes suddenly fail, manually update the subscription once before retesting.

END OF FILE / C-007

If the eight chapters above haven't solved your issue, when asking for help it helps to include three things: client name and platform, steps to reproduce, and a key log excerpt (with your subscription link and token removed). Short, high-frequency questions are covered in the FAQ; to start over from scratch, go back to the setup guide; to switch or upgrade clients, head to the downloads page — Clash Plus is the top recommendation across all platforms.