Clash Troubleshooting Guide

General Workflow: Locate the Failing Layer First

"It's not working" carries almost no diagnostic information. Clash handles a network request across four layers: the client and kernel handle sending and receiving traffic; the system proxy decides which traffic gets routed through the client; the node link carries traffic out to its destination; and rules plus DNS decide exactly how each connection gets routed. If any one layer breaks, the browser shows the same generic "can't reach this page" error. The point of troubleshooting is to pin the failure down to one specific layer and fix that — get the layer wrong, and switching to ten different providers won't fix a system proxy that was never actually applied.

Layer One Check: Logs and Ports

Open the client's log page and set the level to info. When the kernel is healthy, you'll see entries for config loading and port listening; if the log is blank or spamming errors, the problem is with the client itself — skip straight to Chapter 8. A few keywords are worth remembering: bind errors usually mean a port conflict, parse errors mean the config failed to load, and dial errors mean the node connection failed. Verify the port is listening with one command:

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

An HTTP 204 response means the entire chain — client, node, and rules — is working, and the problem lies with the system proxy or browser layer. A timeout or connection refused means you need to keep checking the node and rules. This is the single most-reused check in this whole guide, so it's worth memorizing.

Binary Elimination

Narrow things down in three steps: switch nodes (rule out a single bad node) → switch networks, e.g. mobile hotspot (rule out local broadband blocking) → switch devices, e.g. import the same subscription on your phone (rule out a machine-specific issue). Change one variable per step and the result tells you something immediately. After all three, you should be down to one likely culprit.

Symptom Quick Reference

Skip the workflow and jump straight to the matching symptom:

No Internet: Proxy Is On But Pages Won't Load

This is the most common symptom: every toggle is on in the client, yet the browser times out on everything. Work through the steps below in order — each has a clear pass/fail check, so don't skip ahead.

Step 1: Verify the Client-to-Node Link

Use the curl command from the previous chapter. If it passes, the client, node, and rules are all fine — skip to Step 3 and check the system proxy. If it fails, move to Step 2.

Step 2: Check Proxy Mode and Node Selection

Clients generally offer three modes: Global (all traffic goes through the proxy), Rule (traffic is split by rule), and Direct (nothing goes through the proxy). Accidentally landing on "Direct" looks exactly like the proxy being off even though it's technically on. Switch to Global mode and test again: if pages load in Global mode, the link is fine and the rules are routing your target site to Direct or to a dead node group — go back and clean up your rules and policy groups. If Global mode still fails, try a different node; if every node fails, move on to Chapter 3.

Step 3: Confirm the System Proxy Is Actually Applied

Windows: Settings → Network & Internet → Proxy — "Use a proxy server" should be on, with address 127.0.0.1 and a port matching the client's mixed port (default 7890). Security software or similar tools reverting this setting is a common cause. macOS: System Settings → Network → your active adapter → Details → Proxies — check that Web Proxy and Secure Web Proxy are enabled with the correct port. See Chapter 7 for a deeper dive into this specific check.

Step 4: Firewall and Security Software

Windows Firewall or third-party antivirus tools can block the kernel process from reaching the network: if you clicked "Deny" on the "Allow access" prompt during first launch, the client will appear to be running while not a single packet gets through. Allow the client and kernel process through your firewall, or reinstall the client and click Allow when the prompt appears.

Node Timeout: Latency Tests All Show Timeout

Don't panic if every latency test comes back red — "everything failed" and "a few failed" are two completely different failures with completely different fixes.

Everything Failed: The Problem Is Local or With the Subscription

If every node times out simultaneously, it's rarely all your nodes going down at once. More likely: local network blocking (broadband, campus network, or corporate network blocking the proxy port), an expired plan or exhausted data quota, or an incorrect system clock. Test on your phone's mobile hotspot first: if everything works there, it's your local broadband — try a different protocol (e.g. switch from Trojan to Hysteria2) or nodes with different port characteristics.

System Clock Drift Is a Silent Killer

Protocols like Trojan, VLESS, and Hysteria all run over TLS, and the handshake checks certificate validity against the system clock. If your system time is off by even a few minutes, every TLS-based node will fail its handshake at once — looking exactly like a total node outage. Sync the clock with this command:

# Windows (run as administrator)
w32tm /resync

# macOS
sudo sntp -sS time.apple.com

# Linux
timedatectl set-ntp true

Restart the client after syncing and test again. Devices that rarely connect to the internet to sync time — routers, or machines left off for long stretches — are especially prone to this.

Only Some Timeouts: Node-Specific Issues

If only some nodes time out, it's usually a dead node, provider-targeted blocking, or that particular node's protocol fingerprint being flagged by the local network. Just switch nodes; if an entire region fails, switch regions instead. Keep in mind how latency testing actually works: the client sends an HTTPS request to a test URL and times the response — it's not an ICMP ping. If the test URL itself is unreachable, it'll also show Timeout, so try switching to a more reliable test URL in settings to double-check.

Plan and Subscription Status

When a provider plan expires or the data quota runs out, the subscription link and node list may still be there, but nothing works. Log into the provider's dashboard to check plan status; some clients display usage info from the subscription response headers, which is worth checking too. If the subscription itself won't update, see Chapter 4.

Subscription Failure: Update Errors

"Update failed" is just the surface message — most clients show a more specific reason underneath: a network error (timeout, connection refused), a parsing error (yaml, base64), or an HTTP status code (403, 404). Read the full error first, then match it to the cause.

Verify the Subscription Link Itself

Paste the subscription link directly into your browser's address bar: if it downloads a text file, the link is valid. A 403 usually means an expired token or plan, while a 404 means a typo in the link or a reset subscription. Manual copying is error-prone — missing characters, stray spaces — so re-copy the full link from your provider's dashboard. A typical subscription link looks like this:

https://example.com/api/v1/client/subscribe?token=xxxx

The token is your access credential — leaking it is equivalent to handing over your plan to someone else, so don't paste the full link anywhere public while troubleshooting.

Subscription Domain Is Blocked

If the subscription server's domain itself is blocked, updating over a direct connection will always fail. Two options: enable "Update subscription via proxy" in the client settings (naming varies slightly by client), or connect through a temporary node first and then update the subscription. Once the update succeeds, the nodes in the subscription will work normally.

Format and Parsing Issues

What the subscription returns must be a YAML config Clash can read, or a node list it can convert. If your provider only offers a generic v2ray subscription, switch to their dedicated "Clash subscription" link or use a subscription conversion service. If you've hand-edited the subscription file, watch your YAML indentation — a bad indent shows up as a parsing failure.

Auto-Update Interval

Node lists change on the provider's end over time, and if you never update, you can end up with a list of nodes that are all present but all dead. Turn on auto-update in client settings, with an interval of roughly 24 hours — frequent enough to stay current without being disruptive. For exact setting locations and a full breakdown of failure causes, see the blog post Common Causes of Clash Subscription Update Failures and How to Set Up Auto-Update.

Slow Speed: Working But Sluggish

Slowness is a relative failure — the link works, but the experience is poor. Locate the bottleneck first, then decide whether to switch nodes, switch protocols, or adjust rules.

Locating the Bottleneck in Three Segments

A connection's speed is limited by whichever of three segments is narrowest: local-to-node, the node's own bandwidth, and node-to-destination. To diagnose: on the same node, try different destination sites — if only a few sites are slow, the bottleneck is the node's route back to that particular site; if everything is slow, try a different node for comparison. Noticeable improvement points to node bandwidth or the local-to-node link; if switching nodes never helps, check your local network and the client itself.

Low Latency Doesn't Mean High Speed

Latency determines responsiveness; bandwidth determines throughput. A low-latency node can still be jammed during peak evening hours. Judge speed by actual download or video-loading performance, not just the latency number — a 50ms node and a 150ms node may look identical when streaming video.

Choosing a Policy Group

A url-test group automatically picks the lowest-latency node, but that node might also be the most congested one. Load balancing spreads connections across multiple nodes and suits downloads well. Manual selection gives you the most control — cycle through a few similarly-latent nodes to find the most stable one at that moment. If a destination site is being routed through a roundabout node group by your rules, that will also slow things down: open the connections panel to see which rule and node a connection actually hit, and adjust rule order or pin that site to a specific node if needed.

Protocol and Kernel Differences

Newer UDP-based protocols (Hysteria2, TUIC) noticeably outperform traditional TCP-based protocols on lossy, high-jitter connections. The mihomo kernel fully supports both — the top desktop picks Clash Plus and Clash Verge Rev, along with FlClash, all ship with mihomo built in. For more on kernel and protocol differences, see the blog post mihomo (Clash Meta) Kernel Features vs. Original Clash.

DNS Issues: Resolution Errors and Poisoning

Typical Symptoms

Proxy connects fine, but some sites won't load; a site loads in the "wrong region" version; ad-filtering rules work inconsistently; nslookup returns an obviously wrong IP. All of these point to DNS, not the node.

How Clash's DNS Module Works

The client's built-in DNS module takes over domain resolution from the system, queries the configured upstream servers, and works with rules to decide who resolves a domain and where the result goes. Two modes: redir-host returns the real resolved IP; fake-ip returns a virtual IP from the 198.18.0.0/16 range, and the kernel forwards by domain name once the connection is established — faster resolution, naturally resistant to DNS poisoning, and the default mode for most clients.

Example Configuration

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fake-ip-filter:
    - "*.lan"
    - localhost.ptlogin2.qq.com

nameserver handles resolution for direct-connect domains, while fallback handles domains routed through the proxy. fake-ip-filter lists domains that must return a real IP (LAN devices, and certain IP-sensitive apps). Changes to the dns section only take effect after restarting the kernel or reloading the config — most clients have a one-click option for this in settings.

Clear Caches After Changing Config

Both the OS and the browser cache DNS results, and if you don't clear the old cache, a new config can look like it didn't take effect:

Checking for DNS Leaks

With the proxy on, visit a DNS leak test site: the resolver shown should be your proxy's exit point or your configured upstream, not your local ISP. If your local ISP shows up, check whether the system DNS is hardcoded, or whether the browser's "Secure DNS" is bypassing the system resolver.

System Proxy Not Working: Toggle Is On But Traffic Isn't Routed

First, Confirm What "Working" Looks Like

With the system proxy on, visit an IP lookup site in your browser — the exit location shown should match your node's region. If it still shows your local ISP, the proxy isn't actually active. This check takes ten seconds, so do it before digging further.

Windows: Check If the Proxy Setting Got Overwritten

Settings → Network & Internet → Proxy: "Use a proxy server" should be on, address 127.0.0.1, port matching the client. Security software or other proxy tools can silently overwrite this setting. The client also needs permission to write to system settings — if needed, run it as administrator once to grant that access.

macOS: Permissions and Proxy Settings

System Settings → Network → your active adapter → Details → Proxies — check that Web Proxy and Secure Web Proxy are enabled with the right port. The first time the client tries to enable the system proxy, macOS shows a permission prompt — if you clicked "Don't Allow," it can never write the setting again. Allow it in Privacy & Security settings, then try again.

Browser-Level Interference

Extensions like SwitchyOmega take over the browser's proxy settings and can conflict with the system proxy — pick one or the other. A browser's "Secure DNS" feature bypasses the client's DNS logic entirely, showing up as "the IP changed but content looks wrong" — disable it first when troubleshooting.

Terminal and Dev Tools Ignore the System Proxy

Terminals ignore the system proxy by default and need explicit environment variables:

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

git, npm, and pip each have their own proxy settings, and environment variables don't always cover everything. For a full walkthrough covering both browsers and terminals, see the blog post Troubleshooting Clash System Proxy Not Working.

The Definitive Fix: TUN Mode

TUN mode uses a virtual network adapter to intercept all system traffic, bypassing system proxy settings entirely. It works for apps that ignore the system proxy (games, some command-line tools), and sidesteps recurring issues like proxy settings getting overwritten. See the blog post How to Enable Clash TUN Mode for how it works and setup steps.

Client Crashes and Startup Failures

First, Figure Out What's Actually Crashing

A crashing UI and a failing kernel are two different problems. When the kernel fails, the client usually shows a specific message (core failed to start, port in use, config parsing error) — read it before doing anything. If the UI itself won't even open, reinstalling or switching clients is usually the faster path.

Port Conflicts

If the mixed port or the external controller port is already in use — often by a leftover client process that didn't shut down cleanly last time — the kernel simply won't start. Check what's using the port:

# Windows (run as administrator)
netstat -ano | findstr :7890

# macOS / Linux
lsof -i :7890

Kill the conflicting process, or switch to a different set of ports in client settings. After changing ports, remember to check that the system proxy settings use the matching port too.

Config File Syntax Errors

YAML is extremely sensitive to indentation: spaces only, no tabs, and one wrong level means a parsing failure. After hand-editing config.yaml, run it through the client's built-in config check or a YAML validator. A valid node entry looks like this:

proxies:
  - name: "Node A"
    type: trojan
    server: example.com
    port: 443
    password: "your-password"
    sni: example.com

Permissions and System Components

On Windows, TUN mode and service mode both require installing a system service (most clients have a one-click installer for this). On macOS, Enhanced Mode requires authorization on first use. Security software may quarantine the kernel binary by mistake — whitelist it, then reinstall the client.

Reset and Reinstall

A general fix for a corrupted config directory: back up your subscription link → quit the client → rename the config directory → relaunch and re-import. If that still doesn't work, switch clients: Clash Plus is the top pick for Windows and macOS, with Clash Verge Rev and FlClash as alternatives. Clash for Windows and ClashX Meta are no longer maintained and aren't recommended for new installs. See the full client list by platform on the Downloads page.

Mobile-Specific: Android and iOS

Android: Getting Killed in the Background Is the #1 Cause

Battery optimization on many Android skins kills persistent VPN processes, showing up as the proxy "turning itself off" after the screen has been locked for a while. Fix: Settings → Apps → find the client → Battery/power usage, set to "No restrictions" or "Allow background activity"; lock the client in the recent-apps view; and allow it to auto-start. Clash Meta for Android, FlClash, and Surfboard are all on the Downloads page's Android section, with Clash Plus as the top overall pick.

Android: VPN Slots Are Mutually Exclusive

Android only allows one VPN to run at a time. If another VPN or accelerator is holding that slot, the client will either fail to start or forcibly take over. Using the client's per-app proxy feature to narrow its scope also reduces conflicts with other tools.

iOS: Clash Plus and System-Managed VPN

On iOS, install Clash Plus from the App Store (official site: clashplus.io). iOS manages the VPN connection at the system level, and it generally stays connected through screen lock. Low Power Mode and disabling Background App Refresh can affect subscription auto-updates and staying connected — check both first if updates seem to silently stop happening.

Interoperability With Desktop Configs

Subscription links work across every platform: the same provider subscription can be imported on both your phone and computer, with identical rules and routing logic. Everything covered earlier in this guide about DNS, rules, and protocols applies equally on mobile — the only difference is OS-level background persistence and permissions.

Mobile Symptom Quick Reference