Clash Troubleshooting Guide

This page and the Setup Guide serve distinct purposes: the guide walks through the main path from installation to your first successful connection, ideal if you're setting Clash up for the first time. This page is built for situations where you already have it installed but something isn't working — find the chapter that matches your symptom and work through its steps from top to bottom. Steps within each chapter are ordered by likelihood, so the first few usually resolve most cases. If you haven't installed a client yet, grab an installer from the Download page (Clash Plus is recommended across all platforms), complete the initial setup following the guide, then come back here if you run into trouble.

1. General Approach and Reading the Logs

Before changing any setting, build two habits: locate the problem by layer, and change only one variable at a time. The proxy chain can be split into five layers from top to bottom — the client interface, the core process, configuration and subscriptions, remote nodes, and the local system environment. Where the symptom shows up determines which direction to investigate. Randomly trying the "reinstall, switch subscription, change DNS" combo often turns a single isolated problem into a stack of compounding issues.

The Basic Order for Layer-by-Layer Diagnosis

• Client layer: whether the interface opens normally, whether toggle states match what you expect, and whether any error dialogs appear.
• Core layer: whether the core process is running and whether its listening port is reachable (see the curl verification method in Chapter 2).
• Configuration layer: whether the subscription loaded successfully, which rule mode (Rule/Global/Direct) is selected, and whether rules match the expected exit node.
• Node layer: whether nodes are available, what latency tests show, and whether the subscription has expired.
• System layer: whether the system proxy/TUN is actually applied at the OS level, and whether a firewall or other network software is interfering.

The Logs Page and Log Levels

The logs page is the primary source of information for troubleshooting. Most clients default to the info level, which shows the target domain, matched rule, and final exit node for every connection — enough to answer "which node did this traffic actually go through." When digging into DNS or handshake-level issues, temporarily switch to debug, then switch back once you're done, since the volume of output at that level noticeably slows down the interface.

Minimal Reproducible Config

When you suspect the problem lies in the complexity of your subscription's config, use a minimal config to verify whether the core and node themselves are working. Save the example below as minimal.yaml, swap in the parameters of any working node, and load it as a local config in the client. If the minimal config connects but the full subscription doesn't, the problem is isolated to the subscription's rules or DNS section; if even the minimal config fails, the problem lies at the node or system layer.

mixed-port: 7890
log-level: info
mode: rule
proxies:
  - name: test-node
    type: ss
    server: example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
proxy-groups:
  - name: PROXY
    type: select
    proxies: [test-node]
rules:
  - MATCH,PROXY

2. No Internet After Enabling the Proxy

Symptom: after enabling the client, no website loads at all — or the network doesn't come back even after closing the client. This is one of the most common and most easily misdiagnosed issues; the key is separating "the proxy chain is broken" from "leftover system proxy settings."

Step 1: Confirm Your Basic Local Network

Quit the client and try loading any website directly. If it doesn't load, your local network itself has a problem unrelated to the proxy — deal with your router or ISP first. If it loads, continue to the next step. If the whole network stays down after quitting the client, you're most likely dealing with leftover system proxy settings — skip ahead to the "Clearing Leftover System Proxy Settings" section below.

Step 2: Bypass the Browser and Test the Proxy Port Directly

Browsers have their own proxy cache and extensions that can interfere, making them unreliable test tools. Use curl to send a request directly to the core's port — the result is clean and trustworthy:

# Verify that the core's proxy port is working
curl -x http://127.0.0.1:7890 -I https://www.gstatic.com/generate_204

# HTTP 204 returned → the core and node chain are fine; the problem is at the system proxy layer, see Chapter 7
# connection refused → the core isn't listening, see Chapter 8 (process/port issues)
# Long timeout with no response → the node is unavailable, see Chapter 3

Step 3: Check the Rule Mode and Exit Node

Accidentally switching the mode toggle at the top of the proxy page can also cause a total outage: Global mode routes all traffic through whatever node is currently selected, and if that node is dead, everything fails with it; Direct mode, depending on your network environment, can make some sites unreachable. Stick with Rule mode day-to-day, and confirm that the currently selected node in your policy group shows a green latency result. Also check whether a catch-all block rule like MATCH,REJECT has been accidentally enabled in your subscription — if the logs page shows a large number of connections hitting REJECT, that's the rule blocking them.

Clearing Leftover System Proxy Settings

When a client exits abnormally (crash, force-kill), it doesn't get the chance to restore the system proxy settings, so the system keeps pointing traffic at 127.0.0.1:7890 even though nothing is listening there anymore — this shows up as "the whole network died after I closed the client." Fix: reopen the client and close it normally once; this usually restores things automatically. If not, clear it manually: on Windows, go to Settings → Network & Internet → Proxy and turn off "Use a proxy server"; on macOS, use:

networksetup -setwebproxystate "Wi-Fi" off
networksetup -setsecurewebproxystate "Wi-Fi" off

3. All or Some Nodes Timing Out or Failing Latency Tests

Start by distinguishing "all nodes timing out" from "some nodes timing out" — the causes for each barely overlap.

All Nodes Timing Out

1. Check your system clock. Most encryption protocols are sensitive to time drift; if your system time is off from the standard time by more than a minute or two, handshakes will fail across the board. Turn on automatic time sync, and double-check anything where you've manually changed the time zone.
2. Check whether your subscription has expired. Providers typically keep the node entries visible after expiration but refuse connections, which shows up as every node timing out. Log into your provider's dashboard to check the expiration date, renew, and update the subscription.
3. Check your firewall and security software. If you dismissed the firewall authorization prompt the first time the core ran on Windows, outbound connections may be silently blocked. Go to Windows Security → Firewall & network protection → Allow an app through firewall and confirm the core process is allowed through; the same applies to third-party security software.
4. Cross-check with a different network. Connect your computer to a phone's hotspot and test again. If it works on the hotspot but everything times out on your original network, that network is interfering with the proxy protocol — unrelated to the client or subscription.

Some Nodes Timing Out

It's normal for a handful of nodes to time out: server outages, line fluctuations, or the destination network blocking that node can all cause it. The fix is simple — switch to a node with normal latency, and check back after a few hours or the next subscription update. If nodes in a specific region are consistently dead, report it to your provider; there's nothing to fix on the client side.

Understanding What the Latency Number Actually Means

A latency test sends a single timed request to the address specified in url-test — the number reflects one round trip to that test target, not your actual browsing experience. If the test target itself is unreachable, even a healthy node will show as timed out. You can customize the test address in a policy group:

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies: [node-a, node-b]

For a deeper look at why latency numbers and real-world experience diverge (test target choice, packet loss, bandwidth bottlenecks), see the blog post: Why Clash Latency Numbers Can Be Misleading.

4. Subscription Import and Update Failures

Subscription errors carry a lot of information — start by matching the error keyword against the table below, then check the relevant subsection.

Format Mismatch

If a link works in other apps but fails to import — or imports with no nodes — into Clash, it's almost always a format issue: Clash-based clients expect a complete YAML config, while some links return a Base64-encoded raw node list instead. To tell which one you have, paste the link into a browser and open it: fields like proxies: and rules: mean YAML; a long unbroken string of letters and numbers means Base64. Providers usually offer a dedicated "Clash subscription" link — use that first; otherwise, run it through a subscription converter into Clash format before importing. For a breakdown of the structural differences between formats and conversion caveats, see the blog: Clash Subscription Formats Explained.

The Update Loop Problem

In some network environments, the subscription server can't be reached directly, so the update request itself needs to go through the proxy — but the proxy depends on the nodes from that same subscription, a chicken-and-egg problem. Most clients offer an "update via proxy" toggle in subscription settings: keep it on while your nodes still work; if every node is dead, turn it off, switch to a network that can reach the subscription server directly (like a phone's mobile data hotspot), update once, then switch back after the nodes are restored.

Manual Import as a Fallback

If every automatic update fails, there's still a reliable fallback: open the subscription link directly in a browser, save the response as a .yaml file, and choose "Import local file" on the client's config page. This path bypasses the client's download logic entirely, sidestepping user-agent checks, proxy loops, and any other network-side interference — it's also useful for figuring out whether the link itself is broken or the client's download step is.

5. Connected but Slow

Separate Latency from Bandwidth

There are two kinds of "slow": a long wait before a page starts loading is high latency; low video quality or slow download speeds is insufficient bandwidth. Low latency doesn't mean high bandwidth — a latency test only sends a tiny request and can't measure throughput. The two call for different fixes: for high latency, try a node that's physically closer; for low bandwidth, check the node's rate limit and your local link first.

Troubleshooting Order

1. Compare nodes. Test at least three nodes from different regions in the same subscription. If they're all slow, keep going; if only one is slow, that node is congested — just avoid it.
2. Establish a baseline with a direct-connection speed test. Turn off the proxy and run a speed test against a nearby local server. If your direct connection itself only gets a few tens of Mbps, the proxy can never exceed that — calibrate your expectations accordingly.
3. Check for local bandwidth usage. Download managers, cloud sync clients, and system updates all compete for upload and download bandwidth. Sort the logs or connections page by traffic to find what's eating your bandwidth.
4. Check for misrouted traffic. A misconfigured rule can send local traffic through an overseas node, making local sites feel slow too. Confirm on the logs page that local domains are matching DIRECT; if not, check the rule set order — custom rules often push the GEOIP catch-all rule further down than intended.
5. Cross-check against peak hours. Slowness that only happens at a fixed time each day is a classic sign of line congestion; try a less popular region's node, or confirm the line type with your provider.

6. DNS-Related Issues

The Difference Between the Two Resolution Modes

Clash-based cores handle DNS with two enhanced modes: fake-ip and redir-host. fake-ip answers local queries with fake addresses from the reserved 198.18.0.0/16 range, with the actual resolution happening on the node side — it's fast to match and leaks less, making it the current default. redir-host resolves domains locally instead. For a full breakdown of how it works, see the blog: How Fake-IP DNS Mode Works. A working DNS section typically looks like this:

dns:
  enable: true
  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

Common Symptoms and Fixes

• A site works by IP but not by domain name: something's broken in DNS resolution. Check whether dns.enable is set to true and whether the nameserver entries are reachable; switch logs to debug temporarily to see exactly who each query was sent to and what came back.
• An app shows a connection to 198.18.x.x: that's a fake-ip address that ended up in the hands of a program that isn't going through the proxy. Add that program's domains to fake-ip-filter so those queries return real addresses.
• Local network devices become unreachable (printers, NAS, screen mirroring): fake-ip has taken over local name resolution. Make sure fake-ip-filter includes local suffixes like *.lan and +.local; if the affected device uses a fixed hostname, add that too.
• Resolution breaks across the board after switching networks: the fake-ip cache no longer matches the new network. Run "Clear fake-ip cache" in the client (most clients have this button in settings or on the home screen), or restart the core.
• Online gaming or P2P apps misbehave: these apps are sensitive to real IP addresses and don't play well with fake-ip. Either add filter exceptions for the relevant domains, or switch entirely to redir-host mode and test.

7. System Proxy Not Taking Effect

What System Proxy Can and Can't Do

A "system proxy" simply registers an HTTP proxy address with the operating system — only programs that actively read that setting will actually use it. Browsers and most common desktop apps read it, but command-line tools, some chat and gaming clients, and plenty of background services never do. This isn't a bug, it's a boundary of how the mechanism works. Quick test: if your browser routes through the proxy fine but a specific app doesn't, that app almost certainly doesn't read the system setting.

Making the Command Line Use the Proxy

Terminal tools like git, pip, and npm detect the proxy through environment variables. Set them temporarily for the current 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

On Windows PowerShell, the equivalent is $env:https_proxy="http://127.0.0.1:7890". If you need this permanently, add it to your shell config file — but during troubleshooting, stick to temporary settings so you don't forget to clean up and cause new problems later.

Handing Stubborn Apps Over to TUN Mode

TUN mode creates a virtual network adapter that intercepts all TCP/UDP traffic at the network layer, without relying on any app cooperating — it's the general solution for "this app simply won't go through the proxy no matter what." Here's how the two approaches compare:

System Proxy Toggle Is On but Never Applied

In rare cases, the client shows the toggle as on, but the system settings remain empty — usually due to insufficient permissions or another program overwriting the setting. Try running the client as administrator and toggling again; if that doesn't work, check whether security or network acceleration software is rewriting the proxy setting on startup — you may have to choose one or the other if there's a conflict.

8. Client Crashes and Unexpected Exits

Crashes on Launch: Check Config Parsing First

If the app crashes immediately on launch, or the tray icon flashes and disappears, suspect a config parsing failure first. YAML is extremely sensitive to indentation and the space after a colon — double-check this if you've hand-edited your config. To pinpoint it: find the client's log file (usually in a logs subfolder inside the client's data directory) and check the error entries in the last few lines, which usually include a line number for parsing errors; or switch back to an unmodified subscription, or launch with the minimal config from Chapter 1 — if that starts successfully, it confirms the config was the problem.

Port Already in Use

If another process is already holding the port the core wants to listen on (common when a previous core process didn't fully exit, or another proxy app is running), startup will fail or the app will keep restarting. Check what's using the port:

# Windows
netstat -ano | findstr :7890

# macOS / Linux
lsof -i :7890

Once you've found the process holding the port, close it, or change mixed-port in the client settings to a free port (like 7891) and restart. If you change the port, remember to update every hardcoded 7890 reference in Chapter 7 as well.

Corrupted Cache and a Clean Reinstall

For random crashes during use, a blank white screen, or settings that won't save, try clearing the client's cache: quit the client, go into the data directory, delete the cache-related subfolders (usually containing cache in the name), leave profiles (your subscriptions and configs) untouched, and relaunch. If it's still unstable, do a clean reinstall: back up the profiles folder first, uninstall, manually remove any leftover data directory, grab the current version from the Download page, install it, then restore your backed-up subscription files. If you want to cross-check stability and features between different clients, the Client Comparison Guide can help you pick an alternative.

Documenting Crash Patterns

Occasional crashes are the hardest to diagnose. Keep a record of three things: what you were doing right before the crash, whether TUN was on at the time, and the last twenty lines of the log file. With that information in hand, you'll troubleshoot far more efficiently on your own — or when asking the community for help.

9. Mobile-Specific Issues (Android / iOS)

Android: VPN Authorization and Background Survival

Android clients (Clash Plus is recommended, with alternatives in the Android section of the Download page) take over traffic through the system's VPN interface — on first launch you must approve the system's "Create VPN connection" prompt. If you dismissed it, go to Settings → Network → VPN, delete the app's entry, and re-authorize. If the connection indicator (the key/VPN icon in the status bar) is showing but traffic isn't going through, check the client's per-app proxy settings — apps excluded under blocklist mode, or not checked under allowlist mode, will never be routed through the proxy.

Connections that drop after a while are almost always the system's battery-saving mechanism killing the background process: heavily customized Android skins (MIUI, ColorOS, HarmonyOS, etc.) aggressively reclaim background apps by default. Three fixes to apply together: add the client to the battery optimization allowlist (set to "unrestricted"), lock the app in the recent-apps view, and allow auto-start. If disconnects still happen after all three, enable a "persistent notification" option in the client to raise the process's priority.

iOS: The Memory Limits of Network Extension

iOS clients are distributed through the App Store, with Clash Plus recommended (the iOS section of the Download page links directly to the store listing). On iOS, the proxy runs inside a Network Extension, which the system caps with a strict memory limit — too many nodes in a subscription or an oversized rule set can get the extension process killed outright by the system, showing up as "the VPN icon appears for a second or two and disappears" or frequent auto-disconnects. Fix: ask your provider for a slimmed-down subscription, or use a converter to strip out unused regional nodes and redundant rule sets to shrink the config size; under Rule mode, favor compact GEOIP/GEOSITE rules over plaintext lists with tens of thousands of lines.

Another common iOS behavior: brief connectivity loss after switching between Wi-Fi and cellular. This is the VPN tunnel rebuilding itself after the network change — wait a few seconds and it should resolve on its own; if it doesn't come back, manually reconnect in the client.

Behavioral Differences Between Mobile Data and Wi-Fi

If the same phone works fine on Wi-Fi but every node times out on cellular (or vice versa), one of those two networks is interfering with proxy traffic — unrelated to the client itself: carrier networks sometimes block specific ports or protocols, and public Wi-Fi may have a captive portal or filtering in place. Use this difference to cross-check quickly and narrow the problem down to "network environment" instead of wasting time reinstalling the app. For the complete first-install process and permission setup order on mobile, see the blog post: A Complete Walkthrough of First-Time Clash Setup.