At a glance

Keep system DNS as your baseline. Set a custom DNS server when you need a specific resolver, or consider DNS over HTTPS to encrypt queries between your device and the resolver. This guide covers the differences, how to set dns-server, and how to tell whether a problem occurs during DNS resolution or connection. It's for users with a working service configuration who are troubleshooting unreachable domains or resolution issues after switching networks.

DNS resolves names; it does not determine the connection route

DNS settings in Shadowrocket control how domain names are resolved to IP addresses. This is separate from Global Routing in Home, which determines how connections are routed. When a site won't load, first distinguish between a lookup failure and a connection failure after an address is returned. Avoid changing DNS, rules, and server settings all at once.

Domain lookup Resolver Address returned Connection decision Destination reached

This flow describes a typical request that uses local DNS resolution; not every connection follows exactly the same steps. Apps may reuse cached results or use encrypted DNS themselves. Some proxy connections can send the destination domain to a remote resolver. So after changing dns-server, don't expect every lookup on the device to switch to the new setting immediately.

System DNS, custom DNS, and DoH compared

System DNS uses the resolver provided by the current network environment, usually through Wi-Fi or cellular settings. Custom DNS lets you specify an upstream resolver; entering a plain IP address typically uses traditional DNS transport. DNS over HTTPS (DoH) exchanges DNS messages with a resolver endpoint over HTTPS. These aren't three mutually exclusive categories: DoH is also a way to specify a custom resolver.

Compare DNS configuration methods
Method Resolver source and transport Best first use Keep in mind
System DNS Uses the system-provided resolver; transport depends on the network configuration. Establish a baseline or resolve local network and organization-specific domains. The resolver and results may change when you switch between Wi-Fi and cellular.
Custom DNS Enter a resolver IP address; queries typically use UDP port 53, with TCP port 53 used when needed. Check whether the issue is related to the resolver provided by the current network. Changing the IP address alone does not encrypt DNS queries.
DNS over HTTPS Enter a complete HTTPS endpoint; it typically uses TCP port 443. Encrypt DNS queries between the client and the resolver endpoint. Availability may depend on endpoint reachability, certificate validation, and initial resolution of the endpoint's hostname.

Bottom line: change one variable at a time for the same domain

Keep the network, Global Routing, and selected server unchanged; change only the DNS setting. Keep the change only after confirming the result is repeatable. If you change several things at once, even a working page won't tell you which change fixed the problem.

DoH encrypts DNS traffic between your device and the resolver, not the entire connection. The resolver still processes your query, and the website connection is routed separately. Using DoH doesn't mean all DNS traffic goes through a proxy or that your connection's exit point has changed.

Set dns-server in [General] in Config

In Config, confirm which configuration file is active, back up its contents, and open the file's text editor. The three code blocks below are alternatives; don't paste all of them at once. If the file already has a [General] section, edit dns-server there instead of adding a duplicate setting.

  1. Note the current Global Routing option and selected server in Home so you can compare results under the same conditions.
  2. Open the active file in Config and find [General] and any existing dns-server setting.
  3. Replace only this setting, save, and confirm that the same file is still selected. For a cleaner test, disconnect and reconnect.
  4. Retry the request to the domain and check the result. Existing connections and cached results may still be in use, so don't draw a conclusion from a single page refresh.

Use the system resolver

[General]
dns-server = system

system is a setting value, not a domain to replace. It's a useful troubleshooting baseline, especially on networks with internal domains, router names, or organization-specific records. Public resolvers usually don't know about these records, so switching to public DNS can make internal services unreachable.

Specify a standard DNS address

[General]
dns-server = 1.1.1.1

1.1.1.1 is an example of the syntax for a public resolver; it isn't necessarily faster on every network. You can separate multiple upstreams with commas, but don't assume the order guarantees a strict primary-to-backup failover. For troubleshooting, start with a single resolver to make reachability and response results easier to identify.

Specify a DNS over HTTPS endpoint

[General]
dns-server = https://cloudflare-dns.com/dns-query

A DoH value must include https://, a hostname, and the path required by the service. A regular website homepage URL is not a substitute for a DNS endpoint. This example illustrates the format; check the endpoint published by your resolver before using it. Don't casually replace the hostname with an IP address: certificate identity, service routing, or endpoint support may not allow it.

Check ports and values to verify your settings

53
Standard port for traditional DNS, over UDP or TCP
443
Default HTTPS port, typically used by DoH
2 types
Common address records: A for IPv4 and AAAA for IPv6

Port numbers identify transport; they don't rank speed. Being able to reach DNS over port 53 doesn't guarantee an HTTPS connection to a DoH endpoint will work. Likewise, loading an ordinary HTTPS site doesn't prove a particular DoH service is available. Test the resolver you actually use rather than treating access to any website as evidence that the DNS service is reachable.

System DNS baseline

Configuration section
[General]
Setting name
dns-server
Setting value
system
What to check
On the same network, can both public and internal domains be resolved?

Record the baseline before changing the resolver.

DoH endpoint check

Protocol prefix
https://
Example hostname
cloudflare-dns.com
Example path
/dns-query
What to check
Are initial endpoint resolution, the HTTPS connection, and certificate validation working?

Check every part of the endpoint address; don't verify only the protocol prefix.

If a domain returns an AAAA record but access is unstable, investigate the IPv6 path rather than assuming DNS returned an incorrect address. A resolver returning an address and the current network being able to connect to that address are separate conditions. Don't rely on opening the IP directly in a browser as your only test: HTTPS sites may depend on the domain for certificate validation and virtual host selection.

How DNS relates to Global Routing and rules

In Home under Global Routing, Config evaluates connections against the rules in the active configuration; Proxy and Direct select proxy and direct routing, respectively; Scene relates to choosing a configured scene. When troubleshooting DNS, note the current option. Don't attribute every difference after changing the route to the resolver.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,DIRECT

This snippet explains how rules relate; it isn't a complete configuration and isn't intended to replace your existing rules. GEOIP and IP-CIDR make decisions based on addresses, which may involve an IP returned by DNS; DOMAIN-SUFFIX uses a domain condition. To understand where a connection goes, check both the matching rule and the final policy, not just the DNS response.

How to troubleshoot when a domain won't load

Start with a domain that previously worked, and note whether the issue occurs on Wi-Fi, cellular, or both. The observations below suggest what to check; they aren't test results from this page. After each change, retry the request and record the time, network, and result so you're not comparing different conditions.

DNS symptoms and what to check next
Observed symptom Check first How to verify
After switching to DoH, multiple domains no longer resolve. Endpoint spelling, initial resolution of the endpoint hostname, and HTTPS reachability. Switch back to system DNS as a baseline. If resolution works again, focus on the DoH endpoint rather than rewriting all your rules.
Public websites work, but internal domains don't. Whether you switched to a public resolver that lacks internal records. Restore system DNS on the original network and test the same internal domain again.
An address is returned, but the connection still times out. Matching policy, server reachability, destination port, and IPv6 path. Check the policy and destination in the connection details; don't keep switching DNS blindly.
An app's behavior doesn't change after you update the setting. Cached data, existing connections, and the app's own DNS behavior. Finish the affected requests and try again. Compare a new request, not just a page that's already open.

Connectivity Test can help check server reachability, but it can't prove that every domain used by an app or service resolves correctly. Likewise, a successful DNS lookup doesn't prove the selected server or destination website is reachable. Record DNS results, connection tests, and actual page requests separately.

Bottom line: identify the failure stage before changing settings

If no address is returned, check the resolver and endpoint. If an address is available but the connection fails, check routing and the connection path. If only one app is affected, then check its cache and DNS behavior. Keep the original configuration and revert any change that doesn't resolve the issue. Avoid piling on unverified changes.

Choose settings for your network and use case

Keep a configuration you can understand, reproduce, and restore—not one with the most upstream resolvers. This guide assumes you already have your own service configuration; it does not provide or recommend subscriptions. To learn more about configuration files and connection testing, read the complete manual or the user guide.