Written for people actively working with Clash: how to configure it, and what happens when you configure it wrong, so you only make each mistake once. Articles on the same topic sit together, and Clash Verge Rev entries carry the version they were written against.
Troubleshooting · 18 articles
18 pieces on "Troubleshooting", covering concepts, steps and common problems. Start with the shorter ones for an overview, then dig in.
macOS blocks Clash Verge network extension for TUN: unambiguous Privacy & Security approvals, work from Applications not Downloads, quit competing VPN extensions, reboot when required, verify utun-style front ends and curl egress before swapping nodes—narrow macOS extension path distinct from global proxy vs TUN overview.
Clash “global” but only the browser works: system proxy as voluntary HTTP/SOCKS versus Mihomo TUN at the IP layer, Windows WinINET vs WinHTTP and UWP loopback to localhost proxies, macOS Network Extension approval, firewall and competing VPN conflicts, rule order still hitting DIRECT, and pointers to TUN guide and Verge—not WSL2 or Docker.
Mihomo Sniffer enabled but streaming still matches GEOIP: TLS and QUIC sniff ports, override-destination, DOMAIN-SUFFIX rules before catch-all GEOIP, DNS fake-ip with hijack and TUN alignment, copy-paste YAML, and log-first verification—distinct from product-only domain lists.
When every Clash node shows red on delay test: separate UI probes from real browsing, fix subscription merge and capture mode, align DNS fake-ip with TUN or system proxy, understand UDP and STUN versus TCP response time, tune url-test health checks, and rule out firewall and corporate TLS inspection—cross-platform triage for Mihomo-based clients.
Clash works in the browser but docker pull and builds fail: point Docker Desktop HTTP/HTTPS proxy at the local mixed port, separate WSL2 backend behavior on Windows from engine settings, pass HTTP_PROXY into containers and BuildKit build-args, and tell registry timeouts from routing issues using our WSL2 guide when the complete Linux side is offline.
Windows 11 with Clash and WSL2: when the host works but Linux loses the internet, compare preconfigured routes and Hyper-V vEthernet adapters, system proxy versus TUN, WSL DNS and resolv.conf, front end metrics, and MTU black holes—reproducible checks before reinstalling the client.
Clash works on your PC but phones on the same Wi-Fi cannot use the proxy: verify subnet reachability and guest-network isolation, enable Allow LAN with bind on all front ends, align HTTP, SOCKS, and mixed port fields on the phone, add Windows Defender Firewall inbound rules and macOS incoming allowances, then rule out sleep and port collisions.
Android Clash clients that show no proxy, drop VPN, or fail subscription refresh: step-by-step checks for URLs, TLS, captive portals, battery optimization, background limits, Private DNS, and split-tunnel app lists.
Git operations and GitHub Actions steps time out when only part of the GitHub edge fleet rides a healthy path. Put github.com, API, and raw.githubusercontent.com traffic into a dedicated Clash group ordered above GEOIP. Match TUN or proxy env to the shell or self-hosted runner actually running git. Confirm rule hits in Mihomo before swapping nodes.
CLI ollama pull can idle on pulling manifest or tag lists while unrelated browsing looks healthy. Treat Ollama registry and API paths as their own outbound story: carve DOMAIN-SUFFIX lanes ahead of GEOIP, reflect mirror endpoints if you rewired pulls, reconcile DNS with fake-ip and TUN, and iterate from logs.
<strong>npm</strong>, <strong>pnpm</strong>, and <strong>yarn</strong> behind restricted networks often mix fast <strong>registry.npmjs.org</strong> probes with stalled <strong>tarball HTTPS</strong> GETs ending in <strong>ETIMEDOUT</strong>: fence npmjs-shaped hosts ahead of GEOIP; keep competent domestic mirrors DIRECT; tune TUN, DNS fake-ip alignment, Mihomo logs, and concurrency before blindly rotating nodes.
Discord Windows client upgrade stuck at 0% or voice drops behind Clash: TUN capture versus browser-only proxy, DNS fake-ip alignment, log-first DOMAIN-SUFFIX for discord.com and discord.media-shaped CDN before GEOIP, DISCORD_APP versus DISCORD_MEDIA groups, UDP RTP WebRTC path and NAT—methodology like Epic or Steam launcher guides with Discord host evidence, not recycled steampowered lists.
Mainland portals slow through proxy despite GEOIP snippets: greedy DOMAIN-KEYWORD or RULE-SET rows before GEOIP cn DIRECT, MATCH miswired to flaky groups, DNS fake-ip vs resolver fallback bypassing Mihomo—not Sniffer-first streaming tweaks; first-match reordering, GEOIP positioning, RULE-PROVIDER merge audits, QUIC and IPv6 edge cases versus browser-only TUN guide.
Yacd or Metacubex blank while proxy works: verify external-controller bind and merged YAML, curl /version first, Mixed Content HTTPS vs HTTP API, [::1] vs 127.0.0.1, secret and SPA tokens, Docker or WSL port publishes—a dashboard checklist angle, not port 7890 or Rule Provider repeats.
Steam store blank or download at 0 B/s while the browser works through Clash: TUN vs system proxy for the thick client, DNS and fake-ip alignment, log-first DOMAIN-SUFFIX for steampowered and steamstatic ahead of GEOIP, slow-download vs region mirrors, UDP and NAT for multiplayer, SteamWebHelper on Windows, verification checklist—gaming platform and UDP, not streaming or AI tool domain recycling.
Clash on Windows fails after install or upgrade with port 7890 or mixed-port already in use: netstat and Get-NetTCPConnection to PID, Task Manager mapping, free the listener or edit YAML mixed-port and system proxy, external-controller and duplicate-instance notes, WSL2 and Docker pointer—user-intent port conflict guide, not Allow LAN or TUN repeats.
Public Wi-Fi captive portal with Clash: disable TUN and system proxy to load the login page, re-enable in order, use DIRECT and RFC1918 in rules, fix DNS fake-ip for portal hostnames, mobile OS sign-in first—pairs with the global system proxy vs TUN guide, not subscription-only faults.
Clash and Mihomo rule-providers: fix remote ruleset upgrade failures with correct YAML (type, url, path, behavior, format, interval), PATH permissions and working directory, GitHub or TLS/DNS gotchas, log-first split between download faults and parse faults, and RULE-SET order versus fetch—complements the rule split guide, not a duplicate.
Free and open-source. Supports Windows, macOS, Android, iOS, and Linux. Ready to use in 5 minutes.