Advanced Configuration 14-minute read

Clash DNS Configuration Explained: nameserver, fallback, and DNS Hijacking

Understand Clash DNS request paths, primary and fallback resolvers, fallback filters, and a practical troubleshooting sequence for common failures.

First, confirm where DNS requests actually go

Clash proxy rules decide whether a connection goes direct, through a proxy, or is rejected—but DNS resolution usually happens before rule matching. When a browser opens a domain, the application may call the operating system resolver or send a query directly through built-in encrypted DNS. The OS resolver may then forward the request to the DNS server assigned to the network adapter, the router, or Clash’s local listening port. Only requests that actually reach the Clash DNS module are affected by nameserver, fallback, and fake-ip.

A typical request path looks like this: the application submits a domain, the system or TUN takes over the DNS query, Clash selects an upstream resolver according to policy, the returned address is matched against proxy rules, and a direct or proxied connection is established. If an application bypasses the system resolver, or devices on the LAN still send DNS to the router, changing the Clash configuration will not change those requests.

With system proxy enabled alone, HTTP and HTTPS traffic can enter Clash, but DNS does not necessarily follow. Some browsers resolve domains locally, while some SOCKS clients can hand the domain to the proxy for resolution. TUN mode covers more traffic through routing and DNS hijacking, including programs that ignore system proxy settings, but exceptions still include browser secure DNS, virtual machines with separate networks, and other devices on the LAN.

Four layers involved in one DNS query

  1. Application layer: The browser, command-line tool, or other software chooses system DNS, built-in DoH, or handing the domain to a SOCKS proxy.
  2. System layer: The operating system cache, network-adapter DNS, VPN interface priority, and local hosts file can all produce a result before Clash is involved.
  3. Clash DNS layer: The listening port, enhanced mode, primary and fallback resolvers, and domain policies determine how the query is handled and what is returned.
  4. Connection layer: Clash uses the domain, destination address, and rule set to choose an outbound connection; the node hostname may require a separate lookup as well.

Troubleshoot from one layer to the next instead of repeatedly switching public DNS providers. Pay close attention to caching: the browser, operating system, and Clash may all retain DNS results. If you test the same domain immediately after changing the configuration, an old result may hide the change. Reload the configuration first, then clear the relevant caches or wait for the records to expire.

The roles of dns, default-nameserver, and nameserver

Here is a basic configuration that makes the roles easier to understand. Supported fields vary between the original Clash, Clash Meta (now commonly called mihomo), and client integration versions. In practice, follow the documentation for the current core and the results of its configuration validation.

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://cloudflare-dns.com/dns-query

enable and listen

enable: true turns on the core DNS module. listen sets the local listening address and port; listening on 0.0.0.0 accepts requests from every network interface, so desktop systems should also use firewall rules to restrict external access. If the service is only for explicit local use, consider listening on a loopback address. When TUN forwards DNS hijacks through the core, the exact listening behavior depends on the client and core implementation.

Port conflicts are a common reason a configuration fails to start. Port 53 may already be occupied by a system service, container tool, or another DNS process, so desktop clients often use an unprivileged port such as 1053 and route requests there through TUN or system settings. Do not start two local DNS services at the same time without first checking which ports are in use.

default-nameserver: bootstrap resolution for upstream hostnames

When nameserver uses a DoH or DoT hostname, the core must know the upstream host’s IP address before it can establish the encrypted connection. default-nameserver mainly handles this bootstrap lookup and may also be used for the initial resolution of proxy node hostnames. To avoid the loop of needing the same DNS server to resolve the DNS server itself, compatibility-focused configurations usually list directly reachable IP addresses here.

default-nameserver is not the primary source of answers for ordinary domain lookups. Packing a large number of resolvers into this list will not automatically improve speed; it can instead create inconsistent results and make troubleshooting harder. A small set of reachable, stable resolvers is enough.

nameserver: the default primary resolvers

nameserver provides the main upstreams for regular queries. It can use standard UDP DNS or, when supported by the core, DoH and DoT. Resolvers may differ in how they handle CDN addresses, IPv6 records, and polluted networks. When multiple upstreams share one list, the core may query them in parallel or use an internal strategy; this is not the same as a fixed, one-by-one failover sequence.

Avoid using too many resolvers. The more upstreams you add, the more likely the same domain is to return different CDN addresses, failures become difficult to reproduce, or some requests bypass the intended path. When starting out, keep one primary resolver and one independent fallback resolver, then add redundancy after the path is stable.

How fallback and fallback-filter work together

fallback is not simply “ask the backup server after the primary times out.” In classic Clash configuration semantics, primary and fallback resolvers may query at the same time, after which fallback-filter decides whether the domain or the primary result should use the fallback answer. Understanding the filter conditions is therefore more important than merely adding backup addresses.

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://cloudflare-dns.com/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    geosite:
      - gfw
    ipcidr:
      - 240.0.0.0/4
    domain:
      - "+.google.com"
      - "+.githubusercontent.com"

geoip and geoip-code

With geoip enabled, the core uses the geographic assignment of addresses returned by the primary resolver to decide whether to use the fallback result. For example, with geoip-code: CN, it may switch to the fallback answer when the primary result does not match the specified region. This can help with some cross-region resolution differences, but it depends on the accuracy of the GeoIP database. Cloud services, Anycast, CDNs, and newly allocated addresses may be classified in unexpected regions, so geographic matching is not an absolute verdict.

geosite and domain

geosite can use domain sets to indicate where fallback is preferred, although availability depends on the core and its rule data. domain is better for a small number of domains that must explicitly use the fallback resolver. The +. form generally matches a root domain and its subdomains, but the supported matching syntax varies by version and should be confirmed through configuration validation.

Avoid copying a large number of sites into domain one by one. Longer lists cost more to maintain and can conflict with nameserver-policy, rule sets, or subscription configuration. With mihomo, consider using a resolver policy field that assigns resolvers by domain, making the intent clearer.

ipcidr

ipcidr treats specific address ranges as anomalous or as results that should use fallback. For example, reserved ranges can be filtered when they should not be valid answers for ordinary public domains. Use this field for a clearly observed problem rather than copying large subnet lists from unknown sources. An overly broad filter can keep normal CDN addresses on the fallback path, increasing latency and causing result fluctuations.

Trade-offs when using fallback

More granular resolver roles in mihomo

mihomo extends Clash’s DNS configuration with fields such as nameserver-policy, proxy-server-nameserver, and direct-nameserver. These fields help when business domains, proxy node hostnames, and direct-connection domains should use different resolution paths, but not every older client recognizes them.

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  direct-nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "+.example.net":
      - https://cloudflare-dns.com/dns-query

proxy-server-nameserver is primarily used to resolve the hostname of the proxy node itself. Before the node connects, it cannot depend on a DNS server that is reachable only through that node, or startup will loop. Choose an upstream that the current network can reach directly for node hostname resolution.

direct-nameserver resolves domains used by direct outbound connections, allowing direct sites to receive answers that better fit the local network. Whether it is enabled, when it is called, and how it interacts with rule matching depend on the core version and DNS configuration. When migrating a configuration, check runtime logs instead of only verifying that the YAML loads.

nameserver-policy assigns upstreams by domain or rule set and is more explicit than one global primary/fallback structure. For example, send local-region domains to a local resolver and selected business domains to another group of encrypted resolvers. Policies may overlap, so write the expected matrix first—domain category, upstream, and outbound path—then verify each case.

Choosing between fake-ip and redir-host

enhanced-mode determines how Clash associates DNS queries with subsequent connections. The common modes are fake-ip and redir-host. Both help the core retain domain information, but they work differently.

fake-ip: return reserved addresses and map them to domains

In fake-ip mode, Clash assigns a reserved address to each query, such as an address from 198.18.0.0/16, and records the mapping between that address and the original domain. When the application connects to the address, Clash intercepts the traffic, restores the domain from the mapping, and applies its rules. This usually provides stronger domain-rule matching and reduces ambiguity caused by obtaining a real address before making a decision.

A fake-ip address is meaningful only on a path controlled by Clash. If traffic does not enter Clash and the system or another device tries to reach the reserved address directly, the connection fails. LAN discovery, printers, game consoles, enterprise authentication, time synchronization, and some programs that require real DNS answers may also be incompatible with fake-ip.

dns:
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "time.*.com"
    - "time.*.gov"

Domains listed in fake-ip-filter bypass fake-ip responses and receive real addresses instead. Add filters gradually based on observed failures. A broad wildcard filter weakens fake-ip’s domain-mapping advantage and may also cause some requests to be resolved locally before connecting.

redir-host: return real addresses

redir-host mode usually returns the real IP address to the client and tries to associate the domain during connection handling. It is friendlier to devices and programs that require real addresses, but domain-rule detection may be less reliable than fake-ip in complex forwarding, connection reuse, or IP-only scenarios. Exact behavior also depends on sniffing, the TUN stack, and the core version.

For everyday desktop use, test fake-ip first. If LAN services, enterprise networks, or specific applications are incompatible, add precise filters. If the problem is broad and cannot be filtered reliably, evaluate redir-host instead. After switching modes, clear DNS caches and restart affected applications because old fake-ip records may persist in multiple cache layers.

Handling DNS hijacking in TUN mode

Here, “DNS hijacking” refers to traffic interception in the TUN configuration: DNS requests sent to a specified port are redirected to the Clash DNS module rather than meaning that an ISP has tampered with the answer. It addresses applications that still send port 53 queries to the network adapter’s DNS server or the router.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

any:53 means intercept traditional DNS requests addressed to any destination on port 53. Other formats may be supported by different core versions. If the client’s graphical interface has already generated TUN settings, do not define them again in multiple places, or settings may be overridden and startup may fail.

Traditional DNS hijacking generally covers only UDP or TCP port 53. It cannot automatically intercept DoH when a browser connects directly to an external HTTPS endpoint, nor can it transparently rewrite every DoT request. With the browser’s own secure DNS enabled, its behavior may differ from system tools. During troubleshooting, temporarily make the browser use the system resolver, confirm that the Clash path is stable, and then decide whether to keep the browser’s built-in setting.

Common interception failure scenarios

In a router-side deployment, also verify the gateway and DNS settings distributed by DHCP. Pointing DNS to the side router does not mean every connection will pass through it; pointing the gateway to it does not guarantee that endpoints will avoid custom encrypted DNS. Check the gateway, DNS, forwarding rules, and firewall as one complete path.

A step-by-step troubleshooting sequence for DNS failures

DNS failures can look alike even when they occur at different layers. The sequence below checks everything from configuration loading and listening status to upstream access, rules, and caches. It works well for “web pages will not open,” “some domains time out,” “DNS fails after enabling TUN,” and “the same site keeps returning different results.”

Step 1: Confirm that the current core accepted the configuration

Start with the client logs and configuration status. Check YAML indentation, field types, and protocol URLs for errors. Pay special attention to list indentation, spaces after colons, special characters in domain rules, and fields unsupported by older cores. A graphical client may have a raw subscription, an override, and a merged runtime configuration; use the final active configuration as the source of truth.

Step 2: Confirm that the local DNS port is listening

Check that a process is listening on the configured address and port. If another program occupies the port, the Clash DNS module may fail while other proxy-core features continue running. System proxy status may look normal even though domain-dependent connections fail. After changing the port, update the system DNS forwarder or TUN interception settings as well.

Step 3: Test the primary and fallback resolvers separately

Temporarily keep only one nameserver and disable complex filters to verify that ordinary domains resolve consistently. Then test the fallback upstream on its own. If DoH cannot connect, check whether its hostname can be bootstrapped through default-nameserver and whether the current network permits access to the required address and port.

Step 4: Check for a node-hostname bootstrap loop

If the proxy node uses a hostname while the DNS upstream is reachable only through that node, the core may be unable to resolve the node during startup. The proxy then cannot connect, making the DNS upstream unreachable as well. Use a bootstrap resolver that the current network can reach directly for the node hostname; mihomo users should also check proxy-server-nameserver.

Step 5: Check whether fallback-filter is too broad

Temporarily remove geosite, domain, and broad ipcidr filters, leaving only the smallest configuration. If the problem disappears, restore the conditions one group at a time. When a domain frequently alternates between different answers, record what each upstream returned and how the filter evaluated it instead of adding more backup servers.

Step 6: Confirm that fake-ip traffic really enters Clash

If the query returns an address such as 198.18.0.0/16, fake-ip is working. A subsequent connection failure usually means the traffic was not properly intercepted by TUN, a transparent proxy, or the system proxy. Focus on routing and the application’s proxy path rather than replacing DNS. If only a few LAN or authentication domains fail, add them precisely to fake-ip-filter.

Step 7: Resolve IPv6 inconsistencies

ipv6: false usually prevents Clash DNS from returning AAAA records, but the system, browser, or another resolver may still obtain IPv6 addresses. If IPv6 connectivity is incomplete, an application may try IPv6 first and time out. Make sure system IPv6, Clash DNS settings, TUN routes, and proxy-node capabilities agree instead of changing only one switch.

Step 8: Clear caches and retest under consistent conditions

After reloading the configuration, clear the browser and operating system DNS caches, then restart the target application. Keep the network, domain, operating mode, and policy group fixed during testing so you do not change several variables at once. Verify the DNS response first, then rule matching and outbound selection in the Clash logs, and finally whether the connection is established.

Long-term stability does not come from the number of resolvers, but from clear responsibility boundaries. Start with the smallest useful structure: one set of directly reachable bootstrap resolvers, one set of default primary resolvers, and, when needed, one fallback set. Add policy-based resolution and fake-ip filters only for clear requirements.

  1. Identify the core name and version used by the current client before applying any configuration, rather than using unsupported fields blindly.
  2. Keep default-nameserver short and use it for bootstrapping encrypted DNS and proxy node hostnames.
  3. Choose stable, reachable primary upstreams for nameserver; do not mix in addresses with unclear purposes.
  4. Enable fallback only when there is a real resolution difference, and document the reason for each filter condition.
  5. When using fake-ip, maintain a small, precise filter list and remove exceptions that are no longer needed.
  6. In TUN environments, check DNS interception, routing, IPv6, and the browser’s built-in secure DNS together.
  7. Change one group of fields at a time, keep a rollback copy of the original configuration, and use logs to verify the actual path.

A subscription may already contain a DNS section. If the client’s override feature adds fields with the same names, the final result may replace, merge, or ignore them depending on the implementation. Before updating a subscription, confirm whether custom DNS lives in a separate override or directly in a subscription copy; afterward, inspect the final configuration to ensure it was not overwritten.

For most desktop setups, first resolve two questions: whether requests enter Clash and whether the upstream is reachable. Optimize fallback and policy routing afterward. For router-side and multi-device networks, also verify DHCP, the default gateway, custom DNS on endpoints, and the IPv6 exit path. Drawing the path from application to upstream is usually more effective than continually adding configuration fields.

Download Clash