Shadowrocket DNS Settings: System DNS, Custom DNS, and DNS over HTTPS

Learn how system DNS, custom DNS, and DNS over HTTPS route queries, when to use each, and how to troubleshoot connection failures caused by DNS issues.

At a glance

For internal domains on a work or home network, start with system DNS as a baseline. Use custom DNS when an administrator specifies a resolver address. Choose DNS over HTTPS when you need to encrypt queries between your device and the resolver. If you already have a working configuration, change one DNS setting at a time and retest the same domain to tell a DNS failure from a routing-rule mismatch or a connection failure.

System DNS vs. Custom DNS vs. DoH

dns-server specifies the resolver used by a Shadowrocket configuration; DIRECT and PROXY are traffic routing policies. Switching DNS to DoH does not send all connections through PROXY. Likewise, changing Global Routing in Home does not select a DNS server. First identify which layer you need to test.

OptionWhere queries goWhen to use it
System DNSUses the resolver currently available through the system. The resolver may change when you switch Wi-Fi networks or move to cellular.Use the DNS policy provided by the current network, or check whether an internal domain resolves on that network.
Custom DNS (IP address)Sends queries to the resolver IP specified in the configuration, rather than relying only on the server assigned by the current network.An administrator has provided a resolver address, and the device can reach it on the target network.
DNS over HTTPS(DoH)Wraps DNS queries in HTTPS requests and sends them to a specified endpoint URL.You have a known working DoH endpoint and need to encrypt queries between the client and that resolver.

Custom DNS and DoH are not mutually exclusive: entering a DoH URL manually also specifies a resolver. Here, “custom DNS” refers specifically to entering the IP address of a traditional DNS server, making setup methods and failure modes easier to compare.

53
Default port for traditional DNS over UDP or TCP
443
Default HTTPS port used by DoH
A / AAAA
Query separately for IPv4 and IPv6 address records

How to choose: check internal domains first

If your device needs to reach domains that resolve only on a work or home network, first verify that the resolver you plan to use returns the correct address for those domains. Do this before replacing system DNS; a successful test with a public domain is not a substitute.

Change DNS in Config and retest

This example uses a configuration file on iPhone or iPad. Compare results using the same network, the same known-working connection, and the same set of domains. Record the original configuration, then change one setting at a time. Don’t switch networks, change connections, and edit DNS in the same test.

  1. Record the current setup

    Check the current selection under Home → Global Routing. To test the configuration file’s routing rules, make sure Config is selected and leave it unchanged throughout the test. Note the current network, one domain that works, and one that fails.

  2. Open the active configuration

    Go to Config and locate the currently selected configuration file. Save a copy of the original before editing. For files that support local editing, tap ⓘ next to the file, then Edit Config, and check the existing dns-server setting under [General]. If the file is managed by remote updates, run the comparison using an editable local copy.

  3. Change only the resolver

    Keep the existing rules and change dns-server to a single resolver you want to test. For DoH, use the complete HTTPS URL provided by the DNS service; use the path specified by that provider. Don’t enter multiple resolvers for the comparison, or you won’t know which one answered based only on whether a website loads.

  4. Save and retest

    Save, then verify which file is actually selected under Config. Return to Home, disconnect, and reconnect. In the same app, retry the two domains you noted and record whether the domain is nonexistent, the lookup times out, or an address is returned but the connection fails. Reconnecting does not necessarily clear the app’s DNS cache, so an immediate success alone does not prove the new setting took effect.

The three examples below are alternatives; add only one dns-server entry to the existing [General] section at a time. 192.0.2.53 and dns.example.com are documentation examples, not working DNS services.

[General]
dns-server = system
[General]
dns-server = 192.0.2.53
[General]
dns-server = https://dns.example.com/dns-query

DNS troubleshooting steps

First determine whether the error occurs before DNS resolution or after an address is returned. A “connection timed out” message alone does not point to DNS: an unreachable destination port, a failed proxy connection, or a TLS handshake error can also prevent a page from loading. If logs are available, check the lookup result and subsequent connection result by domain and timestamp.

  1. Start with system DNS as a baseline. On the same network, retry the same domain with dns-server = system. If both the working and failing domains fail, first check that the network is usable and whether public Wi-Fi requires a sign-in. If only one domain fails, verify the full hostname and whether it must be resolved on a specific network.
  2. Distinguish a missing record from no response. NXDOMAIN means the resolver considers the queried name nonexistent; a query timeout means no response arrived within the wait period. No AAAA record does not mean the domain is nonexistent; an A record may still be available. If an internal domain resolves with system DNS but returns NXDOMAIN with another resolver, first check whether that resolver can resolve the internal zone.
  3. Test the DoH endpoint separately. When the endpoint uses a hostname, the client must resolve it before it can establish an HTTPS connection. If system DNS works but switching to DoH causes timeouts, check the URL, network reachability to the endpoint, and device time. Then look for a dependency loop: the endpoint requires a proxy to reach, while the proxy server’s hostname depends on that endpoint for resolution.
  4. Once you have an address, check routing rules and the connection. Under Home → Global Routing, verify the expected mode is selected. With Config, check whether the domain matches the intended DOMAIN-SUFFIX rule or falls through to FINAL. Domain rules can match by hostname; IP-CIDR and GEOIP require address information. If an address was returned but the connection still fails, check the policy actually used, the destination port, and the connection path.

Common issues after switching networks or enabling DoH

Works on work Wi-Fi but not on cellular?

On both networks, use system DNS to look up the same full domain and record each result. If it’s an internal domain, or the resolver is reachable only on the work network, failure on cellular doesn’t necessarily mean the configuration is wrong. Reconnect to the work network and test again. Follow the administrator’s instructions for access rather than repeatedly switching to public resolvers.

Does an error in the browser mean a DoH URL is unavailable?

Not necessarily. Loading a regular webpage is not a complete DoH query, and an endpoint may reject requests that contain no DNS query. Check the hostname and path against the service documentation, then test with an actual domain lookup and use its error details to distinguish hostname resolution, the HTTPS connection, and the DNS response.

One app still fails after changing DNS?

Retry the same hostname in the original app, then compare it with another app. If the results differ, check whether the original app is reusing an existing connection, caching an address, or using its own DNS resolver. Opening a webpage in another app does not prove the original app is using the new setting.

It reconnects automatically after disconnecting. How can I compare?

In Settings → On Demand, check whether any connection conditions apply to the current network. To compare behavior before and after connecting, record the original settings, temporarily pause the relevant conditions if your device allows it, then return to Home and verify the actual connection status before testing. Restore the settings afterward.

Download Shadowrocket for free