Why Configure DNS Before You Debug “Random” Timeouts

When people say “Clash broke my internet,” the failure story often starts in the wrong place. They jump straight to node latency charts, subscription refresh buttons, or TLS error screenshots—useful data, but not the first layer. In Clash Meta class cores (commonly packaged as Mihomo), DNS is not a decorative appendix to proxies: and rules:; it is the upstream that decides which names resolve cleanly, which answers are considered poisoned, and—under enhanced-mode: fake-ip—what your applications even think they are connecting to. If your resolver chain is inconsistent, you can observe perfect “instant DNS” in the OS while TCP stalls, or watch logs that look like dead exits when the real issue is a resolver loop through a policy you never meant to apply to port 443 on a DNS endpoint.

This guide is written for readers who want to design DNS, not only react to it. You will see how to assemble a dns: section with a sane nameserver list, a deliberate fallback ladder guarded by fallback-filter, and a fake-ip-filter that matches how you actually browse. Along the way we separate DNS fallback from policy-group fallback (they share a word, not a mechanism), connect DNS to TUN and hijack behavior, and talk honestly about DNS leaks—what the phrase usually means in proxy contexts, and what still leaks even when Clash answers locally. For routing discipline after DNS is stable, pair this with rules and routing best practices; for the tunnel side, read the TUN mode deep dive so you are not debugging two moving targets at once.

ℹ Vocabulary: Field names in this article follow common Meta-class YAML. GUI exporters sometimes rename or nest keys; treat the semantics as canonical and mirror the exact spelling your client generated when in doubt.

The dns: Skeleton: enable, listen, and IPv6

Start with a minimal skeleton that actually runs. At minimum you want enable: true, a listen address (often 0.0.0.0:53 on routers, or 127.0.0.1:1053 on laptops when something else owns port 53), and explicit IPv6 intent. Many mysterious “works on Wi-Fi, fails on cellular” reports trace to asymmetric AAAA handling, not to your Singapore node. If you do not use IPv6 on that interface, disabling IPv6 resolution at the OS or DNS stage can simplify behavior—but if you do use IPv6, pretending it does not exist will create a different class of hangs.

The snippet below is intentionally boring. Boring DNS is good DNS: you can extend it without inheriting twelve hidden toggles you forgot about.

dns — minimal skeleton (YAML) 
dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true

use-hosts: true lets static OS hosts entries participate—handy for lab names, miserable when malware edits hosts. Pick deliberately. If your GUI already sets listen to a high port, keep it; the lesson is “expose a stable local resolver endpoint,” not “always bind 53.”

enhanced-mode: redir-host versus fake-ip

redir-host returns real records toward the client stack when that is what you want: fewer surprises for LAN hostnames, simpler mental models for split intranet DNS, and sometimes fewer interactions with naive apps that cache addresses aggressively. fake-ip returns addresses from a synthetic pool (see fake-ip-range) so the core can classify flows early and keep domain rules coherent even when upstream answers arrive late or through a different path. Neither mode fixes bad rules; they change when the client sees an address and which address it sees.

The failure mode most readers recognize under fake-ip is “resolved instantly, connected never,” because the application receives a quick answer from Clash while the real resolution and routing story continues on the proxy side. That is not automatically a bug—it is the design—but it punishes incomplete domain coverage. If you run fake-ip, you will almost always maintain a thoughtful fake-ip-filter (covered later) and align your rules with the domains you care about. If you are fighting odd LAN portals, compare your symptoms with the Fake-IP LAN and router bypass guide, which walks RFC1918 bypasses and sniffing that pair with DNS filters in practice.

nameserver: Plain UDP/TCP, DoT, and DoH

The nameserver list is your primary resolver set—the place Clash tries first for ordinary queries. You can mix formats: classic 1.1.1.1, tcp:// or tls:// endpoints, and HTTPS templates such as https://1.1.1.1/dns-query or https://dns.google/dns-query. Encrypted transports help on hostile networks; they also introduce bootstrap questions (who resolves the DoH hostname before DoH works?) that default-nameserver answers.

Keep the list short and observable. Twenty resolvers does not improve privacy; it multiplies timeout windows and makes logs unreadable. Two to four well-chosen upstreams, plus a distinct fallback ladder, beats a pile of identical anycast addresses copied from forum posts.

nameserver — mixed transports (YAML) 
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
    - tls://dns.quad9.net:853

Some profiles add proxy-server-nameserver so resolver traffic itself can ride an outbound when direct DNS is blocked. That is powerful and dangerous: if the outbound is down, you can DNS-starve the entire core. Treat proxy-bound DNS as a scalpel for captive portals and censorship edges, not the default for every home network.

default-nameserver and Bootstrap Traps

default-nameserver is the bootstrap lane: plain resolvers used to resolve the hostnames of your encrypted DNS endpoints, fetch rule-provider URLs, and perform other chicken-and-egg work. If you point every bootstrap query at a DoH URL whose own hostname requires DoH to resolve, you build a tidy deadlock. A common pattern keeps default-nameserver on fast, unencrypted or minimally encrypted resolvers you trust on that uplink—often your ISP or router forwarder in friendly networks, or a well-known anycast UDP address when you are not being hijacked.

default-nameserver — illustration (YAML) 
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29

Replace the addresses with ones appropriate to your region and threat model. The point is structural: bootstrap stays simple; privacy and policy move to the main nameserver and fallback lists once names resolve.

fallback Chain and fallback-filter

fallback is not “spare servers for fun.” In Meta-class behavior, fallback servers participate when answers fail policy checks—think probable hijacks, unexpected domestic IP ranges for global CDNs, or answers that trip geo rules you configured. That makes fallback-filter essential: it defines which IP CIDRs and which GeoIP labels count as “expected” on the primary path. When an answer looks wrong, Clash tries the fallback chain.

A practical starting point combines private-space guards with geo expectations you actually hold. If you live in mainland China and expect domestic CDNs to return Chinese IPs, your filter differs from a reader in North America who expects the same brand names to land on anycast global edges. Copy values from a maintainer you trust, then narrow them as you learn your network—blindly pasting gigantic geo lists without reading them creates silent misrouting.

fallback + fallback-filter — pattern (YAML) 
  fallback:
    - https://dns.google/dns-query
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4
    domain:
      - '+.google.com'
      - '+.facebook.com'
      - '+.youtube.com'

The domain section under fallback-filter lists names that should always use fallback resolvers—useful when certain brands are routinely poisoned on local ISP DNS. Keep this list focused; it is not a second rules section. If you expected policy-based node failover, that is a different mechanism entirely—next section.

Do Not Confuse DNS Fallback With Policy-Group fallback

YAML reuse trips beginners constantly. A policy group of type fallback orders proxies for outbound connections. The DNS fallback: array orders resolvers for DNS answers. Those pipelines connect only indirectly: bad DNS can make a healthy proxy look sick, and a perfect proxy cannot fix a resolver that returns the wrong address for your region. When you tune one, note which log file you are reading—DNS diagnostics and connection diagnostics are related siblings, not duplicates.

If you need structured proxy failover—ordered chains, sticky checks, and automatic skip of dead nodes—see policy groups, url-test, and fallback for the outbound side. This article stays inside the dns: map so you do not cross the streams while editing.

fake-ip-range and fake-ip-filter in Practice

fake-ip-range defines the synthetic pool handed to clients under fake-ip. Keep it in documentation-reserved space—commonly 198.18.0.1/16—to avoid collisions with real routes on your machine. fake-ip-filter enumerates names that should not receive fake answers: LAN suffixes, router portal domains, internal enterprise zones, and anything you need the OS to recognize as a real RFC1918 target alongside your IP-CIDR bypass rules.

fake-ip-filter — typical LAN and service entries (YAML) 
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'routerlogin.net'
    - 'tplinkwifi.net'
    - '+.stun.services.mozilla.com'
    - 'time.*.com'
    - '+.msftconnecttest.com'
    - '+.msftncsi.com'

The exact names you need depend on your hardware and OS probes. Windows connectivity checks, captive-portal tests, and certain STUN endpoints are frequent guests in real profiles because they behave poorly when fed synthetic addresses. Maintain this list like you maintain firewall rules: add when evidence appears, remove when you cannot remember why a line exists.

TUN, DNS Hijack, and Making the OS Actually Use Clash

A perfect dns: section still fails if applications bypass it. System proxy mode relies on cooperative apps; anything that implements its own resolver or talks QUIC to a hard-coded DoH endpoint may never touch Clash’s listener. TUN mode changes coverage by pulling traffic at the routing layer, which is why it shows up in almost every “full device” setup—but TUN also demands you understand hijack/redirection options and whether DHCP DNS on a router downstream is still authoritative for some clients.

When you enable DNS hijack features (wording varies by GUI), you are asking the core to capture DNS-shaped flows and feed them through the internal DNS pipeline. That is powerful for leak reduction and for making fake-ip coherent, but it can surprise lab setups that intentionally run split DNS across VLANs. Document what your router hands out via DHCP and whether guest Wi-Fi still points at an upstream you do not control. For a client that exposes these toggles clearly, skim how to choose a Clash client—transparency matters more for DNS than for pretty latency badges.

What “DNS Leak” Means Here—and How to Sanity-Check

In proxy communities, “DNS leak” usually means either (a) queries exit outside your proxy path to an ISP resolver, revealing domain intent, or (b) two different parts of the stack disagree, so some flows use poisoned or split-horizon answers while others use clean ones—behavior that looks like random breakage. Clash can eliminate many class-(a) issues when TUN and hijack are aligned, but class-(b) persists if browsers ship secure DNS settings that ignore OS policy, or if a corporate VPN rewrites resolver tables underneath you.

Practical checks stay lightweight: watch the core’s DNS log while you query, compare against what dig shows through 127.0.0.1 (or your configured listener), and temporarily disable browser DoH while testing. For ecosystem context on resolver choice and connectivity myths, keep the FAQ entry on DNS and connectivity open in another tab—it frames what the core can and cannot promise when third-party software fights for control of the same sockets.

⚠ Compliance: Respect local law and network policy. This article explains resolver configuration for legitimate privacy and reliability goals—not evading monitoring you are required to honor on employer or campus networks.

A Worked Example You Can Paste and Trim

The block below stitches the pieces into one place. It is not a universal optimum; it is a readable baseline for desktops where you want fake-ip, encrypted primaries, a filtered fallback ladder, and explicit fake-ip exceptions. Trim resolver hostnames, geo codes, and filter lists to match your jurisdiction before you paste into production.

dns — combined example (YAML) 
dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true

  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29

  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query

  fallback:
    - https://dns.google/dns-query
    - tls://dns.quad9.net:853

  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4
    domain:
      - '+.google.com'
      - '+.facebook.com'

  nameserver-policy:
    'geosite:cn':
      - https://doh.pub/dns-query
      - https://dns.alidns.com/dns-query

  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'routerlogin.net'
    - '+.msftconnecttest.com'
    - '+.msftncsi.com'

nameserver-policy is optional but valuable: it forwards specific domains or rule-set tags to resolvers that understand your domestic CDN reality, while keeping global brands on resolvers you trust for accurate international answers. If a policy key references remote rule sets, ensure those providers load reliably; otherwise DNS for matched names fails closed in ways that resemble “the node died” when the node is fine.

Wrap-Up

Treat Clash Meta DNS as three cooperating dials: trustworthy resolution (nameserver), skeptical re-resolution when answers look wrong (fallback + fallback-filter), and honest client-visible addresses for the corners of the internet that break under synthesis (fake-ip-filter). Add TUN only after you can explain how DNS packets reach those dials on your OS. Compared with opaque profiles that hide the dns: map, an explicit configuration trades a few minutes of reading for weeks of calmer debugging—fewer mystery timeouts, fewer false accusations against innocent nodes, and a clearer story when something truly upstream breaks.

→ Download Clash for free and experience the difference once your resolver chain matches how you route—not just how you proxy.