For users who have imported their own configuration and need to troubleshoot domain resolution or change DNS settings. First, distinguish system DNS, custom DNS, and DNS over HTTPS; then check the active Config, rule order, and DNS logs. Change one resolution method at a time and compare results using the same domain. A page loading successfully does not prove DNS is working as expected.
1. Check your platform, active configuration, and what DNS does
Shadowrocket is available for iPhone, iPad, Mac, Windows, Android, and Linux. The iPhone / iPad app is a one-time $2.99 purchase on the App Store; check the App Store listing for system requirements. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free. See the download guide for access details. This article refers to Home, Config, and Settings by function; controls may appear in different places on each platform.
DNS translates domain names into addresses that can be used to connect. For example, visiting www.example.com typically requires an A or AAAA record lookup, which returns an IPv4 or IPv6 address, respectively. A successful lookup only means an answer was returned. It does not mean the destination port is reachable, the TLS handshake will succeed, or the subsequent request will use a particular proxy route.
This is a simplified flow; not every request passes through every step. A domain rule may determine the policy before a local lookup takes place. A cached result may avoid an upstream query, and some proxy connections resolve the destination domain remotely. So it is inaccurate to assume every request follows “local DNS first, then rules.”
- In Home, check the connection status and selected server, and note the current Global Routing option.
- In Config, confirm which configuration is active. Save a copy before changing its DNS settings.
- Make sure you already have a working server or subscription. This site does not provide, sell, or recommend nodes, subscriptions, or proxy services.
2. Choosing between the three DNS options
System DNS, custom DNS, and DNS over HTTPS are not three mutually exclusive protocols. The first two mainly differ in where the resolver information comes from; the third describes the transport used for queries. Manually entering a DoH URL is also a form of custom DNS. For clarity, the sections below cover three common setup approaches.
| Setup method | Source and transport | When to use it | Limitations |
|---|---|---|---|
| System DNS | Uses resolver information provided by the operating system. The actual source depends on the network and system configuration. | When DNS works on the current network, or when you need to access local network domains. | The resolver may change when you switch between Wi-Fi and cellular. This alone does not prove that queries are unencrypted or encrypted. |
| Custom plain DNS | Enter the IP address of a trusted resolver. Plain DNS typically uses UDP / TCP port 53. | When you need a fixed resolver and have confirmed that it is reachable over the current connection. | A fixed address does not mean the connection is encrypted. Public resolvers usually cannot resolve private local network domains. |
| DNS over HTTPS | Sends DNS queries to an HTTPS endpoint, typically over TCP port 443. | When you want to encrypt queries between your device and the resolver, and the endpoint is reliably reachable. | You still need to trust the resolver. The endpoint's domain may need a bootstrap lookup, and certificates or routing can cause problems. |
DoH encrypts queries between your device and the resolver. It does not automatically hide all connection metadata or turn web traffic into a different proxy protocol. If your browser has Secure DNS enabled or an app uses its own DNS resolution, check that query path separately.
Bottom line: Keep a working baseline before making changes
If system DNS works, record the results first. Only test a known, trusted custom endpoint when you have a specific DNS requirement or a clear problem to solve. Avoid adding multiple resolvers from different sources at once, or it will be hard to tell which change affected the results.
3. Set up plain DNS or DoH in Config
Open the active configuration in Config and edit its DNS settings. When editing the text file, the common setting is dns-server under [General]. Check whether the key already exists and edit the existing entry rather than adding a duplicate. Make sure any changes made in the interface or text editor apply to the same configuration.
System and plain DNS
- Configuration section
[General]- Configuration key
dns-server- System source
system- Address format
- For plain DNS, enter the resolver's IP address
Get plain DNS addresses from your network administrator or a DNS service you trust.
DNS over HTTPS
- Protocol prefix
https://- Hostname
- The endpoint domain published by the DNS service
- Request path
- Use the complete path published by the service, commonly
/dns-query - Value to enter
- The DoH endpoint URL, not the service's information page
Endpoint paths are not standardized; don't guess one based on the domain name.
The three snippets below are alternative formats; do not paste them all into the same file. 192.0.2.53 is an example address reserved for documentation, and example.com is an example domain. Neither is a working DNS service provided here.
# Method 1: Use the system DNS source
[General]
dns-server = system
# Method 2: Plain DNS format example; not a working service
[General]
dns-server = 192.0.2.53
# Method 3: DoH format example; not a working service
[General]
dns-server = https://example.com/dns-query
- Get the complete URL from a DNS service you trust. Check the protocol, hostname, port, and path, and make sure you haven't copied extra spaces or non-ASCII punctuation.
- Change only the DNS entry in the active configuration. Save it and confirm that Config still has that configuration selected.
- In Home, disconnect and reconnect so the new connection uses the updated settings. If a download or call is in progress, wait until it finishes first.
- If a remote update manages the configuration, check again after updating to see whether the DNS entry was overwritten. To keep your changes, save them in a configuration copy that you manage.
If a DoH endpoint uses a domain name, its first connection may need to resolve that name to an IP address. This is called bootstrap resolution. Replacing the hostname with an IP address does not always fix the issue, since HTTPS also verifies the certificate against the hostname. Do not enter a DoH URL in a server's Address field or in the Subscribe URL field.
4. How DNS relates to DOMAIN-SUFFIX, GEOIP, and FINAL
Rules determine which policy a request follows; DNS determines which address belongs to a domain. They can affect each other, but neither replaces the other. To use the rules in your configuration, select Config under Global Routing in Home. Proxy, Direct, Config, and Scene are different routing modes. When testing, do not change the mode and the resolver at the same time, or you won't know which change caused the result.
[Rule]
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY
This example only illustrates how matching works; it is not a complete replacement for your existing configuration. PROXY must have a valid meaning in your own configuration, and the documentation-only address range 192.0.2.0/24 is not a real service address. Do not overwrite existing policy groups or rules just to copy the example.
DOMAIN-SUFFIXmatches a domain suffix, such asexample.comand its subdomains. When the domain is available, this type of match usually does not require the destination IP to be resolved first.IP-CIDRmatches an address range. If a request starts with a domain name, matching may require DNS resolution; if the request already uses an IP address, it does not.GEOIPmakes decisions based on an IP geolocation database, not a domain suffix or account region. Different DNS results can affect which rule matches.FINALis the fallback policy when no earlier rule matches. It does not configure DNS and should appear at the end of the rule list.
If a domain rule already matches Direct, changing DNS to DoH alone will not switch the connection to Proxy. Likewise, a connected status in Home does not confirm that DNS queries are going through the selected server. Check the query path, matched rule, and final connection policy separately.
5. How to verify DNS results after a change
Use a test domain whose purpose you understand, and keep the network, server, Global Routing mode, and destination page unchanged. Prefer a test subdomain you have not visited before to reduce the effect of caching. A command-line lookup that bypasses the system does not prove which path Shadowrocket actually uses.
- Record a baseline. Before making changes, note the network type, active Config, DNS source, and what happens—for example, “the domain resolves, but the HTTPS connection times out.” Avoid vague notes like “slow” or “not working.”
- Check the server connection. In Home, use Connectivity Test to check the current server. A successful test does not guarantee that every website's DNS, certificate, or application endpoint is working.
- Make a fresh request. Save the DNS settings and reconnect, then close the existing page before testing again. If needed, fully quit the test app to avoid reusing an existing connection.
- Review available logs. In the logs or connection history, check the domain, returned address, matched rule, and final policy. Displayed fields vary by platform. If the resolver address is not shown, do not guess where the query went.
- Repeat, then roll back. Run several tests on the same network, then restore the original DNS setting and compare again. If only the new configuration fails, roll back to the working setup first, then investigate the endpoint.
| Observed result | What you can conclude | Next step |
|---|---|---|
| NXDOMAIN returned | The resolver says the domain does not exist; this is different from a query timeout. | Check the spelling and compare with the original DNS method. |
| DNS query timed out | No response arrived in time. The network, route, or endpoint may be unreachable. | Restore the baseline and check connectivity on plain DNS port 53 or DoH port 443. |
| A / AAAA records returned, but the page still fails | An address was obtained; the problem may be with a later connection step. | Check the rule policy, destination port, TLS, and IPv6 path. |
| DoH certificate error | HTTPS identity verification failed; this is not the same as a domain with no DNS record. | Check the endpoint hostname, system time, and network authentication status. |
Multiple IP addresses or different results on two lookups do not by themselves indicate a DNS problem. CDNs may return different results based on the resolver's network location, region, and load. Browsers can also cache DNS results and connections, so “change it and refresh once” is not a sufficient test. DNS test pages that infer results from your source IP only observe the path used by that particular test.
6. Common issues and how to roll back
All domains stopped working after switching to DoH. What should I change first?
In Config, restore the original dns-server value, save, and reconnect. If things work again, check the complete DoH URL, certificate hostname, and endpoint reachability separately. Do not rebuild the server, replace the rules, and change DNS all at once.
Public websites work, but local devices at home won't resolve. Why?
Switch back to system DNS for comparison and check whether your router provides local domain resolution. Public resolvers usually do not have records for home or company networks. If you need split DNS, use settings provided by your network administrator rather than sending internal device names to an arbitrary public resolver.
Why did my DNS setting change back after updating a subscription?
First, distinguish a server subscription update from a remote Config update. Updating a server list alone does not change DNS, but a remote Config update may overwrite its DNS entry. Check the selected file and its contents in Config, and compare them with the backup you made before editing if needed.
Could automatic reconnection affect my test after I disconnect?
In Settings → On Demand, check whether any automatic connection conditions are enabled. Note and temporarily disable the relevant conditions, then test disconnecting and reconnecting. Restore the original settings when you're done. On Demand controls when a connection is established; it does not select a DNS resolver.
Keep troubleshooting reversible: start with the original configuration, make one DNS change, check the resolution result, check the matched rule, then inspect the connection. If only one app is affected, first check whether it uses its own DNS, an existing connection, or an app-level proxy. If the whole network is affected, check network authentication, resolver reachability, and the active Config. If you use a configuration from your own service provider, share only the necessary error details with them; do not expose the full subscription URL, access tokens, or authentication parameters.