Why partial breakage is the normal shape of IPv6 + proxy bugs
When every site failed, you would blame a dead node or a broken subscription URL import. Partial failures point to divergent paths. Modern sites publish both IPv4 and IPv6. Your operating system, browser, and middle boxes may prefer one family depending on Happy Eyeballs timers, routing metrics, and cached answers. Clash sits in the middle: it can proxy one socket and miss another, resolve names with one mode while the app uses another, or apply GEOIP to an address that never matched the domain rule you care about because the connection already left as raw IP.
The mental model is not “IPv6 is broken.” It is “two parallel internets share one hostname, and my policy must be consistent across both.” That is why this article is not a generic TLS or DNS encyclopedia—you can read TLS handshake triage when handshakes fail everywhere. Here we focus on stack-specific alignment: Clash IPv6 toggles in the client, how Fake-IP and Redir-Host interact with AAAA, how split routing order interacts with DIRECT versus proxy outbounds, and when only TUN mode sees the symptomatic flow.
Step 1: Align OS IPv6, interface reachability, and Clash core IPv6
Start with boring facts. Does the machine actually have a global IPv6 address on the interface you use for browsing? On many laptops, Wi-Fi carries IPv4-only while Ethernet has both; VPN drivers sometimes register a virtual adapter that advertises v6 even when upstream is v4-only. If the OS believes IPv6 exists, applications will attempt AAAA lookups and v6 connects. If your Clash core is set to ignore or mishandle IPv6, you create an asymmetric fork: IPv4 rides the tunnel you configured; IPv6 walks a default route that black-holes or lands on the wrong country.
Open your client’s settings and locate the explicit IPv6 switch for the engine (wording varies by GUI; the underlying Meta/mihomo profile may expose ipv6: true in parallel with tun stacks). If the toggle exists, treat it as a contract: “this process will participate in v6 forwarding.” Turning it on without fixing DNS and rules usually changes symptoms rather than magically fixing them—still, leaving it off while the OS aggressively uses AAAA is a guaranteed recipe for half-working pages. Document the before/after: note whether your log shows v6 dial attempts, whether outbounds list v6 bind errors, and whether your node hostnames resolve to v6 addresses you never tested.
Confirm basic reachability outside Clash only to detect ISP-level breakage. If bare v6 to the internet is already flaky, Clash cannot invent stability; you may need prefix delegation fixes, router advertisements, or temporarily turning off v6 at the OS while you finish proxy alignment. The point of this step is to stop debugging YAML when the interface itself is lying about capability.
Step 2: Make DNS mode, AAAA, and upstreams explicit
DNS is where Fake-IP and dual-stack meet user confusion. In Fake-IP mode, Clash answers some queries locally with synthetic addresses so domain rules can trigger on connection setup. In Redir-Host mode, remote resolution plays a larger role, which changes how you reason about split routing and local names. Neither mode removes the need to understand AAAA: if your upstream resolver returns IPv6 addresses for a site you intend to proxy, but the subsequent connection path is not the one your rules assumed, you still lose.
Walk through this checklist slowly. First, list which nameservers your profile actually uses—DoH endpoints, plain UDP, bootstrap constraints—and whether nameserver-policy routes specific suffixes to different resolvers. Split DNS is powerful for corporate intranets; it is also how you accidentally resolve a public hostname through a resolver that optimizes for a country you are not using for the TCP session. Second, disable browser “secure DNS” during testing. Chromium’s DoH can bypass the OS resolver that Clash depends on in some capture modes, which duplicates the “works in curl, fails in Chrome” class of bugs—only now IPv6 makes the mismatch more frequent because CDNs prefer v6 for certain edges.
Third, read the dedicated comparison in Fake-IP versus Redir-Host troubleshooting with your symptoms in mind. If you recently flipped modes while experimenting with IPv6, revert to a known baseline, import a clean profile from your subscription URL, and reapply customizations in small diffs so you can attribute changes. Large merged templates hide duplicate keys and stale DNS blocks that look like v6 issues.
Step 3: Audit rule order, policy groups, and IP-family boundaries
Split routing lives in the rules: array. Clash walks from top to bottom and stops at the first match. That simplicity is dangerous when GEOIP,CN,DIRECT or broad IP-CIDR lines sit above fine-grained domain rules: a destination can match earlier than you expect, especially if the connection arrived as an IP after resolution. With IPv6, GEOIP databases and prefix ownership can differ from mental shortcuts about “domestic” traffic. A domestic-looking v6 range might still be anycast to an overseas edge; conversely, some international CDNs announce v6 blocks that your GEOIP rule labels differently from v4.
Give important services explicit DOMAIN-SUFFIX or rule-set entries that point to the correct policy group before broad GEOIP gates. If you route streaming or banking through a named SELECT group, keep that group stable during tests—flapping url-test health checks between regions recreates the same “some sites, some of the time” feeling as bad DNS. The structural habits in policy groups and Rule Providers apply unchanged; what changes is your awareness that each rule must make sense for both A and AAAA outcomes when both are in play.
If you import remote rule providers, diff updates occasionally. A provider that adds aggressive REJECT lines or reorders GEOIP blocks can shift only the IPv6 path if your local overrides assumed a different precedence. Treat rule churn as operational work, not a one-time import.
Step 4: Choose capture mode deliberately—system proxy versus TUN for v6 sockets
System proxy settings influence applications that honor WinINET, macOS system proxies, or manual SOCKS configuration. Many modern clients open QUIC over UDP, attempt Happy Eyeballs across v4/v6, or ignore application-level proxy for subprocesses. TUN mode creates a virtual interface so more traffic is forced through the same decision engine at layer three, which is often the difference between “browser OK, app stuck” and uniform behavior.
Use Clash TUN versus system proxy for the platform-specific checklist: permissions on Windows, signed drivers, macOS helper trust, and the recovery order when enabling TUN briefly showed “no internet.” Once TUN is on, revisit Step 1: some stacks require IPv6 enabled on the tunnel interface itself. If logs show v6 packets leaving the tunnel but not returning, your issue may be MTU, neighbor discovery, or an upstream filter—note it separately from YAML mistakes.
Step 5: Hunt resolver and browser bypasses that prefer IPv6
Even with perfect YAML, parallel DNS paths break dual-stack coherence. Extensions, antivirus web filters, and “performance” suites inject their own resolvers or short-circuit queries. IPv6-heavy CDNs amplify the damage because the bypass returns different addresses than Clash used when it evaluated domain rules for an earlier handshake.
Run a boring experiment: replicate the failing site in a fresh browser profile without extensions, with secure DNS disabled, while Clash verbose logging records the hostname, matched rule, and outbound. If the clean profile works, reintroduce extensions in binary-search fashion rather than blaming Clash IPv6. On mobile, repeat on Wi-Fi versus cellular; carriers routinely expose IPv6 with different DNS than your home router, which is why “only on 5G” bugs persist until you see the split.
Where router-level DNS hijack or split routing on a gateway competes with desktop Clash, document which hop owns answers for that subnet. Our gateway-oriented notes in OpenWrt and desktop coexistence help when the LAN resolver and the PC client disagree by design.
Step 6: Run a decisive dual-stack A/B and keep written notes
Science beats superstition. After Steps 1–5, perform two controlled tests on the same machine and same browser profile. Test A: IPv6 enabled end-to-end with your intended Clash settings. Test B: IPv6 disabled at the OS or interface level for that session only, with everything else identical. If Test B instantly clears the symptom, you have confirmed a dual-stack interaction rather than a dead proxy node. If both fail, pivot back to TLS, time sync, or subscription health using the relevant guides rather than continuing to twiddle AAAA knobs.
When Test B succeeds, avoid permanent v6 shutdown as the only fix unless your environment truly cannot route v6. Instead, return to Step 2 and Step 3 with evidence: capture which hostnames appeared only on v6, which rule matched, and whether the outbound differed from v4. Often the durable fix is reordering rules, pinning a stable node in a service-specific group, or tightening DNS so both families resolve and exit through the same policy path. Write the outcome in one paragraph you can paste next month when a friend asks why “only GitHub” broke.
Keep the Meta core current while you iterate—protocol expectations move, and older builds mis-handle edge cases in UDP or QUIC alongside v6. Follow the Meta upgrade guide on a schedule that matches your tolerance for churn; routing clarity is wasted if the executor drops packets quietly.
Symptom quick map
| What you see | Most likely layer to inspect first |
|---|---|
| Works on IPv4-only Wi-Fi, fails on IPv6-rich mobile data | Carrier DNS and Step 5 bypass; confirm logs on that interface |
Browser fails, command-line curl -4 works |
Browser secure DNS or v6 preference; compare with Step 2 and Step 5 |
| Intermittent loads on the same site | Flapping policy groups or Happy Eyeballs racing different exits |
| Domestic sites break, international OK (or the reverse) | GEOIP and rule order against v6 ranges; explicit DOMAIN rules from logs |
| Everything broke right after toggling TUN | Virtual adapter conflict, permissions, or MTU—return to Step 4 recovery flow |
Open source and upstream references
Implementation details move between releases. For authoritative syntax and issue searches, the mihomo repository remains the ground truth. Treat GitHub as documentation and source code—not as the primary place to download GUI installers; packages belong with the project’s official release channels and, for day-to-day installs, the on-site download flow we link below.
Frequently asked questions
Is IPv6 mandatory for modern Clash? No. Many users run IPv4-only paths successfully. What matters is consistency: if the OS uses v6, your proxy stack must handle it or you must disable v6 intentionally until alignment is done.
Will turning on TUN always fix IPv6? It fixes many capture gaps but not broken upstream v6 or confused local policy. Pair TUN with DNS and rule audits.
How do I know if Fake-IP is the culprit? Switch modes in a controlled test, compare logs for the same hostname, and read the Fake-IP guide—symptoms overlap with unrelated DNS issues, so evidence beats naming.
Closing thoughts
Clash IPv6 problems rarely need exotic tricks; they need ordered evidence. When split routing, Fake-IP, and TUN stack together, partial site failures are exactly what you should expect until every layer agrees on address family, resolver path, and rule match. Compared with opaque one-button VPN products, explicit YAML plus disciplined logging turns “only this bank” into a solvable ticket: you see the hostname, the outbound, and the fix. Keep your subscription URL imports clean, move custom rules in small steps, and revisit this ladder whenever your ISP or OS updates dual-stack behavior.
If you value that transparency—knowing why a flow went DIRECT instead of guessing—Clash Meta’s model continues to reward patient operators in 2026 more than apps that hide routing behind a cartoon switch.
For broader rule design, continue with the YAML routing guide; for more scenarios, browse the full tech column.