This guide is for users who have selected a server in Home and want to change how domain names are resolved. Start with system DNS as a working baseline, then check dns-server in the active configuration under Config. To use DNS over HTTPS, enter a complete endpoint you have verified and test resolution, rules, and connectivity separately. Any steps involving a proxy connection assume you already have your own service provider and subscription.
DNS settings affect name resolution, not connection routing
DNS settings in Shadowrocket determine how domain names are resolved to IP addresses. When you visit a domain in a browser, getting an address and establishing a connection are two separate steps. Successful resolution only confirms that an address was returned; it does not prove that the service at that address is reachable or that the selected server can complete the connection.
Use Home to select a server and control the connection, Config to manage configuration files, and Settings to adjust app preferences. This guide uses the text configuration in Config to explain DNS, making the changes easy to identify. Before you begin, confirm which configuration is active so you do not edit an unused copy.
Under Global Routing, Config applies the rules in your configuration; Proxy and Direct set the corresponding global routing modes; Scene applies settings for the selected scene. These modes are not DNS transport methods. Selecting Proxy does not automatically switch all DNS queries to DoH, and selecting Direct does not prove that queries use system DNS.
When to use system DNS, custom DNS, or DoH
Here, “custom DNS” means manually entering the address of a traditional DNS resolver. More broadly, entering a DoH endpoint is also a custom setting. Distinguish between who handles the DNS query and how it is sent; otherwise, changing an address can be mistaken for encrypting DNS traffic.
System DNS
RecommendedUse the resolver environment currently provided by the system. It is a useful baseline for initial setup and troubleshooting, with fewer variables such as unreachable endpoints or certificate errors. This is a recommended starting point, not necessarily the best choice for every network.
Best for: first-time setup, restoring a baseline, and accessing network resources that rely on local DNS
Custom traditional DNS
Specify the IP address of a known DNS resolver. Traditional DNS does not encrypt traffic, and reachability depends on the current network and routing. Changing the IP address alone will not resolve every domain access issue.
Best for: networks where an administrator specifies a resolver, or when comparing resolution results
DNS over HTTPS
Send DNS queries over HTTPS to an endpoint that supports DoH. Use the complete URL provided by the DNS service; a regular website homepage is not a DNS API. This protects traffic to the endpoint, but the DNS service can still process the queries.
Best for: a trusted, reachable DoH endpoint and encrypted DNS traffic
Bottom line: establish a working baseline first
If system DNS can reach the target domain, save that configuration before switching to DoH. If access fails only after the change, check the endpoint and the connection to it first. Avoid changing the server and routing rules at the same time.
Configure DNS in Config: back up first, then change one setting
In a text configuration, DNS is commonly set with dns-server under [General]. These steps change DNS resolution in the current configuration; there is no need to re-import an existing subscription. If the configuration is updated remotely, keep a local copy first, since a later update may overwrite local changes.
-
Record the baseline
In Home, note the selected server and current Global Routing mode. In Config, confirm which configuration is active and use its action menu to save a copy.
-
Open the text editor
Go to Config → tap ⓘ next to the active configuration → Edit Plain Text. Find the existing
[General]section anddns-serverentry. Edit the existing value rather than adding a duplicate key. -
Enter the DNS setting
To restore system DNS, enter
dns-server = system. For traditional DNS, enter the IP address of a resolver you have verified. For DoH, enter the complete HTTPS endpoint provided by the service. -
Save and reconnect
After saving, return to Config and confirm that the edited configuration is still active. Go to Home, disconnect, and reconnect so the test uses the reloaded settings.
-
Test the domain again
Retry the target domain on the same network, with the same server and routing mode. Note whether DNS returns a result and whether the subsequent connection succeeds, then decide whether to keep or revert the change.
Use this minimal configuration to restore system DNS. It illustrates the relevant setting; it is not a file to replace your entire configuration with. If [General] already exists, change only the corresponding line and keep the other settings and rules.
[General]
dns-server = systemEntering a DoH URL: full endpoint, certificates, and initial resolution
A DoH endpoint includes a scheme, hostname, and service path. A common path is /dns-query, but not every service uses it. Copy the endpoint supplied by the DNS service rather than assembling one yourself. If the endpoint specifies a non-default port, keep it in the URL.
[General]
dns-server = https://resolver.example.com/dns-queryresolver.example.com above is a reserved example domain for illustrating the format; it is not a working DNS service endpoint. Use a valid endpoint of your own. Preserve the URL's required capitalization, path, and parameters. Do not enter a regular webpage URL or a subscription link in the DNS field.
- HTTPS handshake: An incorrect device clock, an untrusted certificate, or a hostname mismatch can cause the request to fail before it is sent. Check the time and the server certificate first; do not bypass certificate validation.
- Initial resolution: If the endpoint uses a hostname, its address must be resolved before connecting to it. If initial resolution is unavailable, switching to DoH may still time out; the problem may not be the domain you are trying to access.
- Endpoint routing: Connecting to the DoH service is itself a connection. Its routing and dependencies must work, so avoid a loop where connecting to the DNS service depends on that same service.
- Response content: A regular webpage loading does not mean the DoH API at the same hostname works. An incorrect API path, failed authentication, or an HTML response is not a DNS response.
Do not replace a hostname with an arbitrary IP address to fix HTTPS. This can break certificate hostname validation and remove hostname information required by the service. If you need a fixed address, use a configuration method supported by the DNS service and the app.
Troubleshooting DNS: distinguish missing answers, incorrect answers, and connection failures
Before troubleshooting, preserve the failure conditions: network type, target domain, active configuration, Global Routing mode, and a brief description of the error. Change one variable at a time. If you update a subscription, change servers, and modify DNS together, even a successful result will not reveal which change fixed the issue.
| Symptom | Check first | Next step |
|---|---|---|
| Multiple domains time out after switching to DoH | Complete endpoint URL, certificate, and endpoint reachability | Restore system DNS and test again; revisit DoH only after the baseline works |
| DNS returns an address, but the page connection times out | The policy actually applied and the server connection | Check Global Routing and the configuration rules; do not keep changing DNS first |
| Public domains work, but internal domains fail | Whether the domain depends on DNS provided by the local network | Restore system DNS on the current network and test again; then assess local DNS requirements |
| Wi-Fi works, but cellular data fails | Whether the DNS endpoint is reachable on each network | Keep the server and configuration fixed, switch only the network, and record each result |
| No change after editing the configuration | Whether the edited configuration is active and whether an existing connection is being reused | Confirm the selected configuration in Config, reconnect, and retry the request |
Troubleshooting rules requires understanding both domain-based and IP-based conditions. DOMAIN-SUFFIX matches domain suffixes; IP-CIDR and GEOIP match IP-based conditions; FINAL handles connections that did not match earlier rules. A different DNS result may affect IP-based rule matches, but it does not automatically fix rule order.
Comparing Config and Proxy under Global Routing can help identify the effect of rules, but do not treat a temporary routing mode as a permanent fix. If the issue occurs only in Config, check which policy is actually being matched. For IP-based rules, also check for options such as no-resolve that affect DNS resolution.
Bottom line: once an address is returned, check the connection path
If the same domain consistently returns an address but the connection still fails, focus on the policy, server, and destination service. Rotating DNS providers adds variables and makes it harder to isolate the failure.
What to check before saving, and how to restore settings
Test DNS settings on the networks where you actually use them. Public DNS services may not know internal home or office hostnames, and encrypted transport does not guarantee results better suited to your network. If you need access to both internal and public services, confirm your local DNS requirements before adding more complex settings.
- Check the configuration source: After a remote configuration update, check
dns-serveragain. Subscription updates primarily sync server information provided by your service provider; they are not a standard fix for DNS problems. - Check automatic connections: In Settings → On Demand, check whether on-demand connections are enabled. If the app reconnects immediately after you disconnect manually, confirm the automatic connection conditions before assuming your changes were not saved.
- Check IPv6: Receiving an AAAA record and having a working IPv6 connection are two different things. If an address is returned but the connection fails, check IPv6 reachability on the current network rather than drawing conclusions from the record type alone.
- Restore a minimal baseline: Restore the backup or set
dns-server = system, then reconnect and test again. Once the baseline works, add back only the settings you need, one at a time.
Shadowrocket is a closed-source, paid app for Apple platforms, primarily used on iPhone and iPad. The App Store is the only place to get it. Check the App Store listing for system requirements. The one-time app purchase and any service subscription are separate; DNS settings do not add or replace a service you already have.