For Shadowrocket DNS setup, start with system DNS as a baseline, then decide whether to specify a resolver or use DNS over HTTPS based on the results and network restrictions. This guide is for users who have already obtained a subscription from their provider and can import a configuration. It covers dns-server examples, how to edit the setting, and how to troubleshoot by symptom. DNS method, rule policy, and actual connection route are separate concerns; changing one address alone does not tell you where all traffic goes.
1. Separate DNS resolution, rule matching, and connection routing
DNS translates domain names into addresses needed for connections, such as IPv4 A records or IPv6 AAAA records. It does not provide proxy routes or determine whether a website allows access. Even after a successful lookup, a request can fail because of rule selection, the proxy connection, the destination port, or the TLS handshake.
In Shadowrocket, Home → Global Routing determines how traffic is handled. With Config selected, the configuration rules control routing. DOMAIN-SUFFIX can match domain names, while IP-CIDR and GEOIP match based on addresses. Whether a rule triggers a local lookup also depends on rule options and the form of the request. Do not assume that every request first queries the local DNS server.
- Which resolver is used: the system resolver, a manually specified standard DNS server, or a DNS service that supports DoH.
- Which rule applies: the request matches DIRECT, PROXY, REJECT, or a policy defined in the configuration; if no earlier rule matches, check FINAL.
- Where the connection goes: check the current Global Routing mode, the matched policy, and the selected server. The IP returned by DNS alone does not reveal the route.
Check the connection mode firstBefore troubleshooting configuration rules, check that Home → Global Routing is set to Config. Proxy, Direct, and Scene are different test conditions. In particular, do not change the mode and DNS at the same time, or you will not know which change affected the result.
2. Choosing system DNS, custom DNS, or DoH
These options differ mainly in where the resolver comes from and how queries are sent—not in a fixed speed ranking. System DNS usually changes with the Wi-Fi or cellular network. Specifying a standard DNS server makes the resolver explicit, but queries may still be affected by network restrictions on port 53. DoH sends DNS queries over HTTPS, adding requirements for endpoint reachability, certificates, and initial resolution.
System DNS: establish a baseline
RecommendedUse the resolver provided by the current system network to check whether Shadowrocket works as expected in your existing network environment. The resolver may change when you switch networks, so working DNS over Wi-Fi does not guarantee the same results over cellular.
Best for: initial setup, resolving local network names, and restoring a baseline for troubleshooting.
Custom standard DNS: specify a resolver
Specify a resolver IP in dns-server to keep the target consistent. Standard DNS usually uses UDP 53 and may also use TCP 53. Switching to a public resolver may prevent resolution of internal network names, so do not judge it solely by whether public websites load.
Best for: abnormal system DNS results, when you have confirmed the specified resolver is reachable on the current network.
DNS over HTTPS: encrypted DNS queries
Send DNS queries to a full HTTPS endpoint, typically over TCP 443. This protects query traffic between your device and the DNS service. It does not automatically route application traffic through a proxy, nor does it prevent the DNS service from seeing the domain names you query.
Best for: encrypting DNS queries when the endpoint address, certificate, and network connectivity have all been verified.
Bottom line: change one DNS method at a time
First record the result for the same domain using system DNS, then switch to a resolver you have confirmed is reachable. Do not change Global Routing, servers, and rules at the same time. Keep the original configuration so you can attribute any improvement or failure to DNS.
3. How to configure dns-server
dns-server belongs in the [General] section of the configuration file. The snippets below show three alternative settings; do not put all three lines with the same key in the file. When editing an existing configuration, replace the existing key and leave the other settings in the same section intact. Adding multiple keys with the same name makes it difficult to tell which value is active.
System DNS
[General]
dns-server = system
Specify standard DNS
[General]
dns-server = 1.1.1.1, 8.8.8.8
The IPs here illustrate comma-separated syntax; they are not guaranteed to be reachable or faster on every network. For troubleshooting, start with one address and consider adding more only after checking the result. Do not assume the list order guarantees failover, or use a second address to mask persistent timeouts from the first.
Specify a DoH endpoint
[General]
dns-server = https://dns.example.com/dns-query
dns.example.com is a fictional domain used to demonstrate syntax and cannot be used as-is. Enter the full DoH URL published by your DNS provider, including its required path. A regular website homepage, a subscription URL, or a resolver IP by itself is not a DoH endpoint. The path is not always /dns-query.
-
Keep a copy of the original file
Go to Config, save a copy of the current configuration, and note the current Home → Global Routing value. Do not overwrite your only working configuration.
-
Open the text editor
In Config, find the configuration currently in use, tap ⓘ on the right, then tap Edit Plain Text. Find
[General]and the existingdns-serverentry. -
Replace the existing key
Choose one of the options above and replace the existing value. If
[General]already exists, do not paste the entire section again or change the routing rules in[Rule]. -
Save and reconnect
After saving, confirm that Config still has the file you edited selected, then disconnect and reconnect from Home. Saving the file does not mean the active connection has loaded the updated configuration.
-
Retest under the same conditions
Keep the same Wi-Fi network, server, and Global Routing mode, then make the same request to the same domain. Record whether it succeeds, times out, or returns an error before deciding whether to keep or revert the change.
4. What DoH can and cannot do
Standard DNS queries are not protected by TLS; DoH uses HTTPS to protect traffic between your device and the DoH service. But using encrypted DNS and routing DNS through a proxy are two different things. The actual route also depends on DNS-related options, how the endpoint connects, rules, and the current mode. A URL beginning with https:// alone does not reveal the connection's exit route.
| What you observe | What it tells you | What it does not prove |
|---|---|---|
| Standard DNS returns an A record | The lookup returned an IPv4 address | The destination's TCP 443 port or proxy route is reachable |
| DoH query succeeds | The endpoint connected and processed this query successfully | All app queries use this endpoint |
| DoH connects over TCP 443 | The query uses an HTTPS endpoint | The connection necessarily matches PROXY |
| A webpage takes longer to load the first time | The first request involved extra delay | The delay must be caused by DNS rather than TLS or the destination server |
DoH also has a startup dependency: when the endpoint is a domain name, its reachable address must be resolved first. If resolving the endpoint depends on a proxy connection that has not yet been established, this can cause a delay. If all domains time out after switching to DoH, restore a known-working configuration and check endpoint reachability instead of repeatedly adding more DoH URLs.
- Certificate error: Check the device time, endpoint hostname, and whether the network requires sign-in. Do not disable certificate verification to work around the error.
- Webpage response: The endpoint path may be incorrect, or the request may have been intercepted by a network sign-in page. Opening the homepage in a browser does not mean it supports DoH queries.
- Public domains work, but internal names fail: Public resolvers usually do not know DNS records for home or workplace networks. Restore system DNS to compare.
5. Troubleshoot DNS issues by symptom
“Connected, but webpages won't load” is not enough to identify a DNS issue. Record the domain, network in use, time of failure, Global Routing mode, and error type. Home → Connectivity Test can help check connection status, but passing one connectivity test does not prove every target domain resolved correctly or replace checking the failed request itself.
- Check for a broader outage first: Try two public domains that normally work, then check whether only one site is affected. For a single-site failure, also consider the destination service, matched rules, and certificate issues.
- Compare with system DNS: Set
dns-serverback tosystem, save, and reconnect. If that fixes the issue, check the custom resolver address, port, and reachability on your network. - Distinguish error types:
NXDOMAINmeans the resolver reports that the name does not exist; a timeout means no response arrived within the allotted time. Repeatedly retrying a nonexistent name is not the same as addressing a timeout in the connection path. - Check the address family: A domain may return both A and AAAA records. Getting an AAAA record does not mean the current network has a working IPv6 route. Check the actual connection error rather than assuming the resolver returned an incorrect result.
- Check caches and network changes: Apps and the system may both cache DNS results. Reconnecting does not guarantee that every cache is cleared. Reopen the app, allow the record's TTL to expire, and track Wi-Fi and cellular results separately.
- Review the rules last: If DNS returns a result but the connection fails, check whether an earlier REJECT rule blocked it, whether it matched the expected policy, and whether FINAL sent the request to a working route.
Don't use an IP address to replace a domain-name testMany HTTPS websites rely on domain names for certificate verification and virtual host selection. A certificate error after entering an IP address directly does not prove that DNS is working or failing. Keep the original domain and compare the DNS result with what happens at the subsequent connection stage.
6. FAQ: configuration updates, local networks, and connection changes
Why does changing dns-server seem to have no effect?
First check which file is selected in Config, then open it in the text editor to verify that the value was saved. Return to Home and disconnect, then reconnect. If only one app is unaffected, reopen it and consider caching. Do not conclude that the setting failed based only on reopening the same webpage once.
Why can't I reach device names on my home network after switching to custom DNS?
Set dns-server = system again and reconnect, then test on the same Wi-Fi. Internal names may rely on your router's DNS. Some .local names use mDNS, so do not assume a public resolver can handle them. Check local network access as well instead of continually switching public DNS servers.
Can a subscription update overwrite DNS settings?
First distinguish a server subscription update from a full configuration update. Updating a server list does not necessarily rewrite the entire configuration, but downloading or updating a full configuration may replace local edits. Keep a copy before updating, then check [General] in Config. Get your subscription from your provider; do not put a subscription URL in dns-server.
Can I compare results directly after switching to cellular and reconnecting automatically?
No. Check Settings → On Demand to see whether conditional connection is enabled, then confirm the actual connection status on Home and the Global Routing mode. Switching networks can also change system DNS, the network route, and IPv6 availability. Return to the same network and retest with the other settings held constant.
Keeping a recoverable baseline configuration is easier to maintain than stacking multiple resolvers. Change one setting at a time, and record domain results, connection errors, and network conditions before and after each change. Once DNS resolution succeeds, focus on rules and the connection path rather than continuing to switch DNS servers.