Clash Troubleshooting Handbook

Before You Start: Fix the Variables First

There are many moving parts in a proxy chain: local network, client, core, config file, subscription, node server, target website — a failure at any link can look like "the page won't load." The first rule of troubleshooting is to change one variable at a time; otherwise, even if the problem goes away, you won't know which change actually fixed it, and you'll be starting from scratch next time it recurs.

Record Four Basics Before Touching Anything

• Client and core: which client you're using (Clash Plus, Clash Verge Rev, FlClash, etc.), and whether the core is Meta/mihomo or the original. Core differences directly determine whether certain config fields are recognized — see the blog article Comparing the Three Cores for details.
• Running mode: whether you're on system proxy or TUN, and whether the routing mode is Rule, Global, or Direct. Most "works sometimes, fails other times" issues trace back to the wrong mode.
• Config source: imported from a subscription link, a local YAML file, or processed through a subscription converter. Converted configs need extra scrutiny for issues introduced by the conversion template.
• Scope of the issue: are all websites unreachable, or just some; are all devices affected, or just one. The clearer the scope, the more chapters you can skip below.

Turn the Log Level Up to Debug

Every client provides a log panel, usually defaulting to info, which only records connection setup and rule hits. During troubleshooting, temporarily switch to debug: DNS query progress, rule-by-rule matching, and handshake failure reasons will all be printed. The corresponding field in the local config file:

log-level: debug   # switch back to info once you're done — debug logs are noisy

Binary Search to Isolate the Layer

When you're not sure which layer the problem is in, swap things out in order of "least costly first": switch nodes first (rule out a single bad node) → then switch to Global mode (rule out routing rules) → then swap in a config you know works (rule out subscription issues) → finally switch clients or networks (rule out local machine/network issues). Test after each swap; whichever layer makes the problem disappear is where the fault is.

↑ Back to top

No Internet: Every Website Fails After Enabling the Proxy

Symptom: the client shows "connected," but the browser fails to load any website, including ones that work fine without the proxy. The key here is distinguishing between "traffic isn't reaching the proxy at all" versus "it reaches the proxy but the exit node is unreachable" — the fixes are completely different.

Step 1: Test the Local Proxy Port Directly with curl

Bypass the browser and system proxy settings and send a request directly to the local port — this immediately tells you whether the core itself is working:

# Test a site reachable inside mainland China (verifies the core and direct rules)
curl -I -x http://127.0.0.1:7890 https://www.baidu.com

# Test a 204 probe endpoint (verifies the proxy exit)
curl -I -x http://127.0.0.1:7890 https://www.gstatic.com/generate_204

There are three possible outcomes: both succeed — the core is fine and the issue is at the system proxy layer, jump straight to Chapter 7; the first succeeds but the second times out — direct connections work but the proxy exit doesn't, jump to Chapter 3 to troubleshoot nodes; both are refused (connection refused) — the core isn't listening on that port, keep reading below.

Step 2: Three Reasons the Port Isn't Being Listened On

• Config parsing failed and the core never started. The log will show an error-level YAML parsing failure, commonly caused by misaligned indentation from manual editing, or the original core reading a Meta-only field. Fix the config or switch to a core that supports that syntax.
• The port is already in use by another program. The log reports bind: address already in use. On Windows, run netstat -ano | findstr 7890; on Linux/macOS, run lsof -i :7890 to find the process holding the port — either close it, or change mixed-port in the config and restart.
• The port is only bound to IPv6, or a firewall is blocking it. Check whether an unusual bind-address is set in the config; on Windows, if you dismissed the firewall authorization prompt on first run, go to "Windows Security → Firewall → Allow an app through firewall" and manually allow the client.

Step 3: Residual "No Internet Even With the Proxy Off" Issues

If the client exits abnormally (crashes or gets force-killed), it may not have time to restore the system proxy, leaving the system pointed at a 127.0.0.1 port that no longer exists — this shows up as "no internet unless Clash is running." Fix: relaunch the client and exit it normally once so it restores the setting; or clean up manually — on Windows go to "Settings → Network & Internet → Proxy" and turn off manual proxy, on macOS go to "System Settings → Network → Details → Proxies" and uncheck each entry. TUN mode exiting abnormally can occasionally leave stray virtual adapter routes behind; rebooting clears them.

↑ Back to top

Node Timeouts: Latency Tests All Fail or Turn Red

The latency test in the client isn't a ping — it sends a full request through that node to a probe URL (usually one that returns HTTP 204) and times it. So a "timeout" means at least one link in the full proxy chain — local machine → node server → probe URL — is broken.

Diagnostic Order When All Nodes Time Out

1. Confirm the local network first: turn off the proxy and visit a domestic site directly. If the local connection is down, every node will time out — this is the step most often overlooked.
2. Check whether the subscription has expired: once a provider's plan expires or the data quota runs out, the server rejects authentication, and every node timing out simultaneously is the classic symptom. Check the status on the provider's user panel instead of wasting time in the client.
3. Check the system clock: some encrypted protocols are sensitive to time drift, and handshakes fail silently when device time is too far off. Enable "set time automatically" on both phone and computer.
4. Switch the probe URL and retest: if the probe URL itself is blocked or flaky, even good nodes will show timeouts. Change the test URL in the client settings to a different 204 endpoint and test again.
5. Update the subscription: when a provider changes server IPs or ports, the nodes in an old config naturally all stop working. Manually update the subscription to fetch the latest node list; if the update itself fails, go to Chapter 4.

Partial Timeouts: Normal vs. Abnormal

Individual node failures are normal on any provider's network — a few timing-out nodes need no action, just switch to a working one. What's worth investigating is an entire protocol timing out together — for example, all nodes using one protocol failing while others work fine, which usually means that protocol's fingerprint is being targeted on the current network. Switch protocols for the short term and report it to your provider. Another pattern is "wired connection times out, mobile hotspot works" (or vice versa), which points to the local network blocking a specific port or protocol — common on corporate or campus networks.

Reading the Test Numbers

Also worth noting: low latency doesn't mean high speed. Latency measures round-trip time; whether bandwidth is adequate is a separate question covered in Chapter 5's speed-testing methods. Auto-select groups (url-test) retest and switch on a cycle — frequent node-hopping is also addressed in Chapter 5.

↑ Back to top

Subscription Failures: Import Errors vs. Update Failures

Subscription problems fall into two stages: failing on first import is usually a format issue; failing after previously working fine is usually a network or server-side issue. Check what error the client shows first, then match it against the table below.

Error Message Reference

Format Issues: Know What You're Actually Holding

Clash clients only understand YAML-structured configs, but subscriptions in the wild also come as Base64-encoded node lists or protocol-specific formats. Feed a Base64 subscription straight into a Clash client and you'll get "parse failed." The distinction is simple: open the subscription link in a browser — if it starts with fields like proxies: or proxy-groups:, it's Clash format; a long unbroken string of letters and numbers is Base64. The format differences and conversion mechanics are covered fully in the blog article A Deep Dive into Clash Subscription Formats, including how to self-host a converter.

Update Failures That Come and Go

It's common for the subscription domain itself to be throttled on certain networks, creating a paradox: updating the subscription needs the proxy, but the proxy config comes from the subscription. Most clients offer an "update through proxy" toggle — try the opposite of the current state: leave it on and update while the proxy still works, or turn it off and update directly once the proxy has failed. If both fail, tether to your phone's mobile data to update once from your computer, restore the working proxy, then switch back to the normal network. Some clients also support setting an auto-update interval — 12 or 24 hours is reasonable; overly frequent auto-updates can actually trigger failures when the server is rate-limiting.

↑ Back to top

Slow Speeds: Connected but Bandwidth Falls Short

The precondition for diagnosing speed issues is establishing a baseline: test raw local speed with the proxy off, then test again with it on — only the comparison between the two is meaningful. If your raw local speed is only 50 Mbps, no node can push 200 Mbps through it.

Isolating Where the Bottleneck Is

1. Test speed on several nodes in different regions. If every node is uniformly slow, the bottleneck is likely local (router performance, ISP's international backbone, Wi-Fi signal); if only certain nodes are slow, it's that node's load or route, especially noticeable during peak hours (evenings).
2. Compare protocol overhead. On the same server, a protocol with multiple layers of transport wrapping (e.g., WebSocket + TLS) will naturally have lower throughput than a lightweight protocol — that's expected overhead, not a fault.
3. Check for a double proxy stack. Browser extension proxies or a leftover VPN running alongside Clash means traffic makes two round trips, easily cutting speed in half or worse. Turn off all other proxy tools while troubleshooting.

"Fake Slowness" from Misrouted Traffic

A domestic site suddenly getting slow is rarely a node problem — it's usually that traffic being incorrectly sent through the proxy. A common cause is an outdated GeoIP/GeoSite database: newly added domestic domains and IP ranges aren't in the database yet, so the rule match fails and traffic falls through to the proxy by default. To check: visit a domestic site with the proxy on and look at the connections panel to see whether that connection hit DIRECT or a proxy group. The fix (updating the Geo database and verifying the rule takes effect) is covered step by step in the blog article How to Update the GeoIP and GeoSite Databases.

Tuning the Auto-Select Group

When using url-test auto-select, two parameters directly affect the experience: interval controls the retest cycle, and tolerance controls "how many milliseconds faster a new node needs to be before switching." If tolerance is unset or too small, a few milliseconds of jitter can trigger frequent node switches, and every switch drops the current connection — the experience feels like "the internet cutting in and out." Reference config:

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300      # retest every 5 minutes
    tolerance: 60      # new node must be 60ms+ faster to switch
    proxies:
      - Node A
      - Node B
      - Node C

↑ Back to top

DNS Issues: Resolution Failures, Pollution, and Fake-IP Side Effects

DNS is the most easily overlooked layer in the proxy chain: symptoms usually show up as "some sites won't load," "slow the first time then fine after," or "the displayed IP address looks strange" — rarely a direct DNS error. Understanding Clash's two DNS-enhanced modes is a prerequisite for troubleshooting.

fake-ip vs. redir-host

In fake-ip mode, the core immediately returns a fake IP from a reserved range (default 198.18.0.0/16) for every domain query, deferring the real resolution to the far end of the chain when traffic is actually sent — low latency, no pollution, and the default in most current clients. The trade-off is that the local machine never gets the real IP, and a handful of apps that depend on it (LAN discovery, some networked games, certain banking apps) can misbehave. redir-host resolves the real address locally first, then matches rules — better compatibility, but the resolution itself can be polluted. Neither mode is strictly better; switch based on the symptom.

Common Symptoms and Fixes

• Lots of sites stop loading after switching networks, restarting the client fixes it: the fake-ip mapping cache is stale for the new network. Most clients offer a "clear fake-ip cache" button, or just restart the core.
• LAN devices (printers, NAS) behave oddly: LAN domains got swept up by fake-ip. Exclude local domains in fake-ip-filter, see the example below.
• DNS still broken after turning the proxy off: TUN mode took over system DNS and didn't restore it on an abnormal exit. Restart the system's network service or reboot the device.
• Certain domains resolve to obviously wrong addresses: the upstream DNS is being polluted — switch nameserver to an encrypted DNS (DoH/DoT).

A Solid Baseline DNS Config

dns:
  enable: true
  listen: 0.0.0.0:53
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "+.msftconnecttest.com"   # let the OS's connectivity probe resolve normally
  nameserver:
    - https://223.5.5.5/dns-query
    - https://120.53.53.53/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

The idea behind this baseline: use domestic encrypted DNS as the primary resolver for speed, an overseas DoH as fallback, and let fallback-filter use GeoIP to check where the resolved address belongs — when the result isn't in the CN range, the fallback answer is used instead, avoiding pollution. Note that fallback-filter depends on the GeoIP database, and a stale database causes the same kind of misjudgment covered in Chapter 5's Geo update.

↑ Back to top

System Proxy Not Working: Browser Fine, But Some Apps Bypass the Proxy

Symptom: the client is running fine and the browser works normally, but some apps (command-line tools, store apps, game clients) send zero traffic through the proxy. The root cause is that "system proxy" is just a suggested setting at the OS level — applications can choose to honor it or ignore it entirely, and behavior varies widely by app type.

Three Categories of Apps That Ignore the System Proxy

CLI Programs: Setting Environment Variables

# Windows PowerShell (valid for the current session)
$env:HTTP_PROXY  = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

# Linux / macOS (add to your shell config file to persist)
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# Verify
curl -I https://www.gstatic.com/generate_204

UWP Apps: Lifting the Loopback Restriction

Windows Store apps are blocked from accessing 127.0.0.1 by default, so when the system proxy points to a local port, these apps simply lose connectivity. Run CheckNetIsolation LoopbackExempt -a -n=<package family name> as administrator to exempt each app individually, or use a GUI tool to check them off in bulk. Full steps, how to find the package family name, and how to verify it worked, are covered in the blog article Fixing Windows UWP Apps That Won't Use the Proxy.

The Permanent Fix: TUN Mode

TUN intercepts all traffic at the network layer through a virtual network adapter, so it doesn't matter whether an app reads the system proxy or not — it's the fundamental solution to "some apps bypass the proxy." Key points for setup: on desktop, you need to grant admin/root permissions to install the virtual adapter service; once enabled, also turn on the core's DNS hijacking, otherwise apps that specify their own DNS will mess up routing; it's mutually exclusive with other VPN software's virtual adapter — only one can run at a time. For TUN setup details on Linux, see the blog article The Full Process of Installing Clash on Linux.

↑ Back to top

Client Crashes: Startup Failures, Unexpected Exits, and Resource Issues

Crash issues fall into three forms: exits immediately on launch, crashes randomly while running, and doesn't exit but memory/CPU usage is abnormal. Each has a different starting point for diagnosis.

Exits Immediately on Launch: Almost Always a Config Problem

The client GUI's startup depends on the core successfully loading the config, and when parsing fails, some clients simply exit rather than showing an error. To diagnose: swap the active config for a minimal working one (just a single DIRECT rule); if it launches fine, the config is the culprit — add sections back one at a time to find the failing field. The most common triggers:

• YAML indentation errors — extra or missing spaces after manual edits; YAML has zero tolerance for indentation mistakes;
• Core mismatch — the config uses Meta/mihomo-only fields (like certain rule types and outbound protocols) while the client is running the original core. See Comparing the Cores for a field support comparison;
• Incomplete rule set/Geo resource downloads — first launch needs to fetch external resources, and some cores exit with an error if the network is unreachable; connect directly first to complete initialization.

Random Crashes While Running

1. Check the client log and the system log: on Windows, check Event Viewer's Application log; on macOS, check Console's crash reports, to determine whether the GUI crashed or the core crashed. If the GUI crashed but the core is still alive (the port still responds to curl), it's usually a UI-layer issue — reinstall or switch clients; if the core crashed, focus on the config and resources.
2. Check for an oversized subscription: parsing and testing thousands of nodes puts heavy memory pressure on low-spec devices — trim the subscription or turn off auto speed-testing and observe.
3. Conflicts with security software: proxy software's behavior pattern is easily flagged as suspicious; add the client's directory to your security software's allowlist and retest.

Abnormal Memory/CPU Usage

Connection count is the biggest factor: scenarios like P2P downloads that open thousands of connections instantly cause normal memory spikes, which should drop back down once connections close. If it doesn't drop, check whether auto speed-testing is too aggressive (multiple url-test groups × short interval × many nodes = a constant testing storm) and widen the interval to 300 seconds or more. For long-running desktop use, prefer an actively maintained client — a side-by-side comparison of maintenance status and resource usage is on the client comparison page; clients that have stopped receiving updates (like Clash for Windows) have no fix pathway when they crash, so migrating to Clash Plus or Clash Verge Rev is recommended.

↑ Back to top

Android-Specific: Background Kills, VPN Conflicts, and System Settings Interference

Android clients run as a system VpnService, and the failure patterns look noticeably different from desktop: desktop issues are mostly config-layer, while Android issues are roughly half caused by the system's management of background services. This chapter applies to the general behavior of clients like Clash Plus, Clash Meta for Android, and FlClash.

Connection Keeps Dropping: Killed in the Background

The proxy disconnecting after the screen has been locked for a while, with the notification icon disappearing, is the classic sign of an aggressive battery-saving policy on many custom Android skins killing the VPN service. Go through these settings one by one:

1. System Settings → Battery → find the client → set to "unrestricted/allow background activity," turn off "automatic management";
2. Lock the client in the recent apps screen (most skins support swipe-down or long-press to lock), to prevent one-tap cleanup from killing it;
3. System Settings → Apps → the client → allow "auto-start" and "start together with associated apps";
4. Enable "launch on boot" in the client, paired with the system's Always-on VPN (Settings → Network → VPN → gear icon → Always-on VPN), so the system relaunches it if killed.

VPN Channel Conflicts

Android only allows one app to hold the VPN channel at a time. When another VPN-type app (including some "accelerator" or "ad filter" tools) starts up, the system silently cuts Clash's channel, and the client just shows "connection dropped." To check: go to Settings → Network → VPN and see which VPN is currently active, then disable the conflicting app. Similarly, if "Private DNS" is set to a specific hostname, DNS queries bypass the client's DNS module entirely, causing misrouted traffic — set Private DNS to "Automatic" or "Off" first when diagnosing DNS-related issues.

Installation and Update Issues

• "There was a problem parsing the package": the downloaded APK doesn't match the device architecture. Nearly all recent devices should use the arm64-v8a build; only very old devices need armeabi-v7a — architecture-specific installers per client are listed in the Android section of the download page; an incomplete download can also throw this error, so try downloading again.
• Install-over-existing fails: a signature mismatch (e.g., the same-named app downloaded from a different source) can't be installed over the existing one — uninstall first. Export your config before uninstalling to avoid losing your subscription.
• VPN authorization prompt never appears after installing: some skins intercept the authorization prompt — go to the system's VPN settings and manually grant authorization to the app once.

Capturing Logs: adb logcat

When the UI doesn't explain what's wrong, capture runtime logs with adb. After installing platform tools on your computer and enabling USB debugging on the phone:

# Show only error-level output, watch for errors at the moment of disconnect
adb logcat *:E

# Filter by package name (use the actual installed client's package name)
adb shell pidof com.github.metacubex.clash.meta
adb logcat --pid <process ID from the previous command>

A VpnService revoked entry in the log means another app grabbed the channel; a memory-related kill entry points back to the battery-saving policy at the start of this chapter. If you need a systematic first-time setup flow on mobile, go back to the setup guide and follow it step by step — most "broken right after install" issues are already avoided by following the main path there.

↑ Back to top

Didn't Find Your Issue?

This page covers eight failure categories with clear, reproducible causes. If your problem isn't among them: if it's a case of "never worked from the first setup," go back to the setup guide and check everything from the start; if you suspect it's a limitation of the client itself, check the client comparison to confirm whether your client supports that feature; if you need to switch or add a client, head to the download page — Clash Plus is the top recommendation across all platforms, with Clash Meta for Android and FlClash as alternatives on Android. Background knowledge and deep-dive troubleshooting on protocols, cores, and subscriptions is continuously updated in the tech notes.