Official Manual / CONFIG REFERENCE
Shadowrocket Configuration and Routing Rules Reference
For your first setup, start with Quick Start to add your existing subscription or server details and confirm that a connection can be established. This page is a reference for ongoing configuration work: jump to a section when you know the field name; if you connect successfully but traffic is not routed as expected, check the policy and rule order first, then review the relevant rules. See the Download Guide for supported devices and download options.
01 / FILE STRUCTURE
Configuration File Structure and Scope
The configuration file determines how the client handles requests; server details determine where a proxy connection goes. These can be changed independently: selecting an existing server on Home does not change the rules file used by Config, and saving another rules file does not replace server credentials. Before editing, confirm which server the active connection uses and which file is in use when Global Routing is set to Config. A familiar name in the file list does not mean that file is active.
Identify the Four Configuration Sections
| Section | Purpose | When to check |
|---|---|---|
[General] | Shared settings, such as resolver options | When the same issue affects multiple unrelated domains |
[Rule] | Select a policy for requests based on matching conditions | When a destination takes the wrong route |
[Host] | Set an address or resolution method for a specific hostname | When a few hostnames resolve to unexpected addresses |
[URL Rewrite] | Match and rewrite a visible URL | When an old address takes you somewhere else |
Names in square brackets mark section boundaries. Before adding a line, look up the nearest section heading above it rather than relying on nearby text. Lines beginning with DOMAIN belong in [Rule]; lines that map a hostname to an address with an equals sign belong in [Host]. For example, if you paste a rule at the end of a file that is still in the [Host] section, correct syntax alone will not make it a rule. If a section with the same name already exists, add the entry there instead of appending another section with that name and expecting it to override the earlier one.
Read a Minimal Configuration Skeleton
[General]
dns-server = system
[Rule]
DOMAIN,assets.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
This skeleton shows only resolver settings and rule syntax; not every file needs all four sections. Shared settings use keys and values, while rules use commas to separate the type, match value, and policy. In this example, requests to the asset host go through DIRECT, other matching requests under the same domain go through PROXY, and unmatched requests fall back to DIRECT. This illustrates how to read a configuration; it is not a default suitable for every network. In particular, do not replace an existing file with it: local access exceptions, server groups, and fallback behavior may all change.
Start with the file currently in use. Save a readable copy that you can select again, then change one thing at a time. After copying code from a web page, check that brackets, equals signs, and commas are still standard ASCII characters. Do not paste a full URL into a domain rule, and do not append explanatory text to a rule line. If an existing remote source maintains the configuration, check whether an update will overwrite local edits. Testing in a separate copy helps distinguish remote updates from manual changes.
Check Whether You Need to Change the Configuration or Server Details
If an existing subscription has an empty server entry, authentication fails, or the same server remains unreachable after you switch rule files, check the server details and basic connectivity first. Do not put a subscription URL in [Rule] or enter a server address in [Host] to make a proxy rule work. Conversely, if the connection works and the same server reaches other destinations, but one domain gets an unexpected policy, start with the relevant configuration section and rule order. A one-time client purchase is not a connection plan. This guide assumes you already have your own subscription or server details; it does not provide, sell, or recommend nodes or subscriptions.
After saving, return to Config to confirm which file is active, then check the selected mode under Global Routing. If files have similar names, give the test copy a distinctive name so you do not mistake one test for another. When handing off your work, state which section you changed, which destinations should behave differently, and which should stay the same. Saying only “it worked after I changed the config” is not enough to establish that the edit fixed it; the network may have changed or an old connection may simply have ended.
Record the original file and settings before testing whether the new file is active. Saving, selecting, and actually using a configuration file are three separate states to verify.
For a closer look at configuration syntax, see Configuration File Sections Explained. When reviewing a configuration, share only a redacted excerpt of the relevant section. Keep the original file on your own device if it contains server credentials, remote configuration URLs, subscription parameters, or real internal hostnames; do not submit it to a public text comparison service.
02 / GENERAL
General: Shared Settings and DNS
If multiple unrelated domains fail to resolve at the same time, check [General] and the current network before adding proxy rules. DNS resolution returns an address; a rule selects a policy. These are separate decisions. Resolving an address does not prove that a connection to it can be established, and seeing a proxy policy selected does not prove that the destination hostname resolved correctly. Check resolution, policy, and connectivity separately to identify which layer needs attention.
Check the Resolution Baseline with dns-server
[General]
dns-server = system
In this example, system means using the resolver provided by the operating system, which helps you compare its behavior on the current network. It does not refer to a specific public DNS service. The resolver and the names it can resolve may differ across home, office, and cellular networks. If an internal hostname resolves on a company network but not elsewhere, first check whether it is meant to be visible only to an internal resolver. Do not assume the difference is caused by a rule.
When editing an existing file, find the dns-server line that is actually in use, note its current value, and replace it in a copy. Do not add a second key with the same name for comparison, or change the resolver, address-family settings, and fallback policy all at once. Test an ordinary domain that usually works, then a domain with the issue, using the same network and server for both. If the baseline test also fails, check the network or shared settings. If only the problem domain fails, also check its [Host] entry, its resolution result, and any specific domain rules.
Distinguish No Result, a Different Result, and a Failed Connection
If there is no result, check that the name is complete, the resolver is reachable over the current network, and any network sign-in step is complete. Different results are not necessarily a problem: a website may return different addresses based on location, carrier, or time of access. For a meaningful comparison, record the network, target name, and address family, then test the same target again. Do not treat a result from another device on a different connection as a definitive answer. If the name resolves but the connection later times out or fails certificate validation, investigate the destination connection or service name instead of continuing to cycle through DNS settings.
Check IPv4 and IPv6 results separately. A website may publish both address types, and a device may not always use the same one to connect. If an IPv4 address works but access by domain name sometimes fails, check which address family the failed connection actually used. Seeing an IPv6 result alone does not prove IPv6 is the cause; confirm that the same target fails over that address and that the current network can reach that address family. If you temporarily change an address-family setting for troubleshooting, save the original value, verify the result, then restore it and investigate the underlying cause.
Understand the Interaction Between Resolution and Routing
Some issues that look like DNS problems are actually about address rules that need an address to evaluate. A domain rule can match a hostname directly; an address rule placed near the top may require the client to resolve the hostname before it can check the network range. To preserve a specific domain exception, make sure its rule comes before address-based rules, and check whether those rules use no-resolve. Do not change shared resolver settings for all requests just to make one address rule match.
If changing the resolver does not produce an immediate difference, you do not need to keep editing the file. Cached DNS results and established connections have their own lifetimes. End the test session and make a new request; if needed, reconnect the client and compare the current result again. If an old page loaded from cache, the request may never have reached the network step you intended to test. A clearly initiated new request is more useful for verification than repeatedly refreshing a page.
Resolver settings are for addressing specific resolution problems, not a universal way to speed up access or replace a connection route. When testing is done, keep enough notes to explain the result: which configuration was used, whether the resolver was system-provided or specified manually, which network the failure occurred on, and whether the target had no address or had an address but could not connect. That way, if the issue happens again, you can check the same layer first instead of repeating every change.
If the target name does not resolve, troubleshoot resolution first. If it resolves but access fails, check the policy for that address, the connection path, and the destination service. Do not confuse “resolves” with “is reachable.”
03 / DOMAIN MATCH
Domain Rules: Exact Matches, Suffixes, and Keywords
When a destination can be identified by a stable hostname, choose the narrowest rule that is easiest to explain. Use DOMAIN for an exception covering one login host. Use DOMAIN-SUFFIX when the base domain and its subdomains genuinely need the same policy. Consider DOMAIN-KEYWORD only when you can accept matches across unrelated domains and cannot use a precise list. Before choosing a rule type, find the request's actual hostname; do not guess from the page title, service name, or a browser abbreviation.
Extract the Rule Value from a Full URL
For https://assets.example.com:443/manual/index.html, the value for a domain rule is assets.example.com. The protocol at the start, port, path, and query parameters are not part of the hostname. A domain rule cannot target only one directory; other paths on the same hostname will be subject to the same domain policy. For a suffix rule, use example.com as the match value. Do not add a leading asterisk or a path.
| Type | Match value | Example that matches | Example that does not match |
|---|---|---|---|
DOMAIN | assets.example.com | assets.example.com | img.assets.example.com |
DOMAIN-SUFFIX | example.com | example.com、img.example.com | notexample.com |
DOMAIN-KEYWORD | example | assets.example.com | assets.test.invalid |
Suffix matching follows domain-label boundaries: the base domain and its subdomains can both match, but another domain that merely ends with the same letters should not. Keyword matching checks whether the hostname contains the specified text. For example, notexample.com is not part of example.com, but it still contains example. This is why short keywords can unexpectedly change behavior for unrelated services. Before using a keyword, list one target that should match and one similarly named target that must remain unchanged.
Put Exceptions Before Broad Matches
[Rule]
DOMAIN,assets.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
This snippet handles the exact hostname first, then applies a suffix rule to the remaining matching destinations. For assets.example.com, both domain conditions could match; the exact rule comes first and determines the policy, so the suffix rule does not get another chance. Swap the lines and the exception will no longer work, even though the exact rule itself is still correct. If the file contains broad rules supplied by its maintainer, review from the top before adding an exception; placing a new line above FINAL alone may not be enough.
One suffix rule cannot represent an entire app. A page may request the main site, a sign-in endpoint, static assets, and media from separate hostnames. If the home page loads but sign-in or images fail, identify the failed request and decide whether it should use the same policy as the main site. Add an exact rule for the actual destination if needed. Do not broaden a rule to a shared keyword or top-level suffix just because several hosts appear on the same page.
Avoid Broadening Rules When the Domain Is Not Visible
The expected domain may not be visible when a user enters an address directly, an app reuses an existing connection, or the client cannot identify the hostname for the current connection. Changing DOMAIN to a broader keyword will not reveal a hostname that is unavailable. Start a new connection and check whether the request uses a name or an address. If the service is actually reached through a fixed address range, investigate address rules instead. Do not treat an address that a domain happened to resolve to as permanently belonging to that domain; it may be shared.
When maintaining domain rules, record both why an entry was added and when it can be removed. Remove temporary troubleshooting exceptions once the issue is understood. Review long-term exceptions periodically to confirm the hostname still serves the same purpose. At minimum, test the target hostname, another hostname under the same suffix, and a commonly used hostname outside that suffix. If all three change, look for an edit to a broad rule or fallback before adding more exceptions.
Domain rules match hostnames, not paths, and do not cover every network request made by an app. Identify the exact request destination before choosing a match scope.
04 / ADDRESS & REQUEST
GEOIP, IP-CIDR, and USER-AGENT
Before using address-based rules, confirm that you want to match the destination address, not the local address used by the device to send the request. IP-CIDR applies to IPv4 ranges; IP-CIDR6 applies to IPv6 ranges. GEOIP uses an IP geolocation database to classify destination addresses by region. None of these replaces precise domain matching. USER-AGENT matches a visible request identifier, which should not be treated as a reliable app identity either.
Limit an Address Range with a Prefix Length
[Rule]
IP-CIDR,192.0.2.10/32,DIRECT,no-resolve
IP-CIDR,192.0.2.0/24,PROXY,no-resolve
IP-CIDR6,2001:db8::/32,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
The first two lines compare IPv4 ranges: /32 specifies a single address, while /24 covers a set of addresses sharing the first three octets. Put a single-address exception before the broader range. The third line shows an IPv6 prefix and does not belong in an IPv4 rule; use /128 to specify a single IPv6 address. The example ranges are for documentation only and should not be used to test a real service. When writing your own range, confirm that you administer it, then enter both the network address and prefix.
Adding no-resolve to the end of an address rule means the client should not actively resolve a domain solely to evaluate that rule. The rule can still be evaluated when the target is already an address or a usable address is available during matching. This does not disable DNS globally, nor does it make a later GEOIP rule behave the same way automatically. If the target is still only a hostname, an address condition with this option may not be evaluable, and later rules can still apply. Getting different policies when accessing the same service by domain and by IP does not necessarily mean a rule is wrong.
Treat Geolocation Classification as a Broad Match
GEOIP,CN,DIRECT sends destination addresses classified as CN by the geolocation database through DIRECT. It does not match Chinese-language websites, account region, device location, or a domain suffix. A content delivery domain may return addresses in different regions, and the same target may resolve differently on different networks. To set a consistent policy for a specific hostname, put its domain rule before the geolocation rule. Do not change routing for an entire region to fix one destination.
When troubleshooting a geolocation rule, record the address actually used by the failed connection, not just an address returned by a manual lookup. If multiple addresses are returned, the connection may not use the first one in the list. If a destination spans multiple ranges, do not combine every observed address into an increasingly broad network range; that could also match unrelated sites sharing those ranges. Use a range as a long-term match only when you control the destination and its address range is reasonably stable.
Visibility Limits of Request Identifier Rules
[Rule]
USER-AGENT,ExampleClient*,DIRECT
FINAL,PROXY
The fictional identifier above illustrates the syntax: if the client can read the relevant request identifier, a value beginning with ExampleClient can match this entry. For a typical encrypted connection, the client may only see the connection destination and may not be able to read the HTTP request headers. Some requests also do not include a usable identifier. Even when visible, an identifier can change after an app update or request-component change, or be shared by other apps. For reliable service matching, use a clear domain instead of changing encryption trust settings to make this rule work.
When comparing address-based and identifier rules, first ask what information the current request provides, then check whether the field is precise enough. A condition cannot match if there is no value to compare, even when its syntax is correct. Test domain exceptions, address ranges, and request identifiers in separate, verifiable scenarios, and note which condition matches first. If results are intermittent, identify a repeatable difference—for example, a request made by entering an address matches reliably, while one made by hostname does not—before changing the condition or order.
A network range is not a substitute for a domain; geolocation is not a website identity; a request identifier is not an app identity. The broader the match condition, the more important it is to test a destination that should not match.
05 / POLICY & ORDER
Policies, Global Routing, and Matching Order
To check whether a rule is taking effect, start by checking Global Routing, not by counting rules. The three modes shown in the interface are Config, Proxy, and Direct. Use Config to test domain exceptions, address conditions, and fallback rules in the selected rule file. Results in the other modes can help diagnose the connection path, but they do not show whether a particular line in [Rule] is correct.
| Mode | Interface label | Troubleshooting use |
|---|---|---|
| Config | Config | Use the selected configuration's rules to evaluate requests handled by the rule system |
| Proxy | Proxy | Compare whether the destination is reachable through the proxy; this does not test individual rule matches |
| Direct | Direct | Compare access to the destination over the current network without a proxy |
Read Interface Modes Separately from Rule Actions
PROXY is an action in a rule line: it sends matching requests through the proxy connection. It cannot create server details or guarantee that the current server can reach the destination. DIRECT sends requests to the destination over the current network without a proxy; it does not bypass access requirements imposed by the system or destination service. REJECT stops matching requests from being forwarded and can explicitly block a destination. What an app displays—an error, timeout, or missing resource—varies, so the symptom alone does not show whether the reject rule matched.
The interface mode Proxy can be confused with PROXY in a configuration file. The former sets the overall routing mode; the latter is an action selected by a matching condition when rules are being evaluated. For ordinary traffic to go direct while one service uses a proxy, you do not need to switch the entire mode to Proxy. Select Config and put the proxy condition in the file. Conversely, to temporarily compare whether the proxy path can connect, there is no need to edit dozens of rules. Note the original mode, run the comparison, then restore it.
Walk Through a Match in File Order
[Rule]
DOMAIN,updates.example.com,DIRECT
DOMAIN,telemetry.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
Read this as a standalone snippet: the first line sends the updated host through Direct, the second rejects another specified host, and the third sends other matching destinations under the same suffix through the proxy. The fourth line handles requests not caught by the rules above that can be classified geographically. FINAL,PROXY catches all requests that did not match an earlier condition. The rejected host is only an example of an exact rejection, not a ready-made list. Before using an entry, check that blocking it will not disrupt essential functionality and keep a clear way to restore access.
For these rules, the first matching entry determines the route; the client does not collect every match and select the most specific one. Move a suffix rule above two exact rules and the exceptions stop working. Move a geolocation rule up and it may catch requests intended for domain rules. To check order, take a specific destination and read from the top, asking at each line: “Is the information needed to evaluate this rule available?” and “Has it matched?” Stop at the first match. Do not explain the result using a more suitable-looking rule farther down the file.
Choose the Destination for Requests Not Listed in the Rules
FINAL needs no domain, region, or network-range value and is usually kept as a single entry at the end of the rules. FINAL,DIRECT sends unlisted requests directly, which suits setups that proxy only explicitly listed destinations. FINAL,PROXY sends the rest through the proxy path, subject to the availability of the selected proxy. When deciding whether to change the fallback, consider how ordinary work, home devices, and newly encountered domains should behave—not just the one site with a current issue. If you keep changing the fallback to fix an individual site, add a precise exception instead.
Test a policy with at least three destinations: one that should match an exact exception, one that should match a broad rule, and one that should reach the fallback. If you have a reject rule, add a request that is safe to fail. After editing, establish new test connections; existing sessions cannot verify a new policy. This helps catch both kinds of error: a new destination did not change as expected, or a destination that should have been unaffected changed too. Address both before keeping the configuration.
06 / HOST
Host: Set the Resolution Result for a Hostname
Use [Host] for a clearly scoped resolution override: a known hostname must resolve to a specific address in a controlled environment, without replacing the resolver used by all domains. This changes the hostname-to-address mapping. If you only want a hostname to use a different route and do not need a fixed address, change [Rule] instead. Combining the two turns a straightforward policy issue into troubleshooting resolution, certificates, and server reachability.
Fixing an Address and Selecting a Policy Are Separate Tasks
[Host]
lab.example.com = 192.0.2.20
[Rule]
DOMAIN,lab.example.com,DIRECT
FINAL,PROXY
In this instructional snippet, a line in [Host] maps the specified name to a documentation address, while a line in [Rule] sends that exact hostname through Direct. Each section does one thing: keeping only the first will not automatically make the connection direct; keeping only the second will not fix the resolution result. If you adapt this structure for a real environment, use a hostname you manage and a real, reachable address. Do not use a documentation address as a download service or diagnostic endpoint.
Put the hostname on the left of the entry, not the protocol, URL path, or port. On the right, use an address appropriate to the scenario. Mapping a hostname does not set the service port or change the hostname in the browser request. If the new address has no service, or nothing is listening on the required port, resolution can succeed while the connection still fails. If multiple sites share an address, make sure the destination server selects the correct service based on the request hostname; a response for some other site does not prove the mapping works.
Check the Limits of a Fixed Address
A manually fixed mapping will not update automatically when the original service's DNS changes. Fixing a service that normally rotates across several addresses to just one removes that flexibility. An entry left behind after a migration can keep a device connecting to an old server. For a long-term entry, document the network it applies to, the hostname, and who maintains the address. For a temporary migration test, define when to remove the entry. Do not turn a public address observed during testing into a permanent mapping.
If an address is reachable only on an office or lab network, failure after switching to cellular may be expected. Preserve the access conditions when testing: which network the device is on, whether the request uses DIRECT, and whether the destination address and listening port are correct. If the request goes through a proxy, also consider whether the proxy endpoint can reach the same address and whether resolution happens locally or remotely. Do not assume that a local mapping will change how a remote endpoint resolves the hostname.
For HTTPS, the hostname must still match the certificate. Even if the mapped address is reachable, a certificate for a different site means the test has not passed. Opening the destination address directly and seeing a page does not prove that access by hostname will work; the hostname can differ between the two requests. If the name does not match, configure the server to serve the test hostname with the correct site configuration and certificate. Do not treat bypassing identity checks as a valid step in setting up a mapping.
Verify Before, After, and Rollback Results
Record resolution and access results before making changes. Then add just one mapping and make a new connection using the original hostname. Check whether the destination address changed, the policy stayed the same, and the service responds correctly to the original name. Next, test another hostname under the same domain that should not be affected. Confirm that you did not also change the shared resolver or a broad rule. If nothing changed, first confirm that the edited file is selected, then check for cached results, an old connection, or a different resolution path.
To roll back, remove your mapping from the test copy or select the previous file, then make a new request and confirm that the address follows the original resolution path again. Do not only remove a related Direct rule: the fixed address would remain, and the next request might still go to the old server. Nor is it enough for the line to disappear from the editor. A successful rollback means a new request resolves as expected. Keep comparison notes until testing is complete, but do not publish real internal names or addresses.
Use
[Host]to manage addresses and[Rule]to manage routing. When testing a fixed address, always make a new request using the original hostname and keep a copy of the configuration that you can restore.
07 / URL REWRITE
URL Rewrite: Rewrite and Redirect Requests
Use [URL Rewrite] to rewrite a visible URL. One example is redirecting an old help page on a test site you manage to a new page on the same site. This is not another way to set a routing policy. [Rule] determines the connection path for the current destination; [URL Rewrite] changes the matching request URL. If you only want a domain to use a proxy, add a rule, not a redirect. A redirect also changes the requested page and request flow.
Narrow the Match to a Specific Scheme, Host, and Path
[URL Rewrite]
^http://docs\.example\.com/old-help$ http://docs.example.com/help 302
This line uses spaces to separate the match expression, target URL, and redirect status. The leading ^ and trailing $ anchor the entire URL; \. in the hostname means a literal dot, not any character. This example matches only the old page without a query string or trailing slash. It does not match deeper paths or the target page itself. Writing these boundaries explicitly makes a rule easier to verify and remove than an expression that matches every similar-looking address.
This example uses plain HTTP to demonstrate behavior when the client can see the full URL; test it in an environment you control. Do not switch a real service from HTTPS to HTTP or weaken certificate validation to copy the example. Being able to identify the hostname of an HTTPS connection does not mean the client can see its full path and query parameters. For a site you maintain, handle a permanent URL migration with a correct server-side redirect so different clients get the same result.
Confirm That a Rewrite Triggers a New Request
In this 302 example, if the app follows the redirect, it sends another request to the new URL. The new destination must be reachable on its own, and you should verify the policy that applies to it separately. A match on the old address does not prove that the new page loaded successfully. Record the two outcomes separately: whether the old request received the expected redirect, and whether the new request returned the expected content. If the second step fails, investigate resolution and policy for the new destination rather than broadening the old match expression.
Do not reuse a help-page redirect for sign-ins, form submissions, or APIs that need to preserve the request method and body. When an app follows a 302, it may use a different method or omit the original request body. Never test with a real request containing session data, credentials, or private query parameters. Even if the hostname stays the same, changing the path can send a request to a handler with a different purpose. Use a static, read-only page without sensitive parameters to avoid these side effects during testing.
Check for Duplicate Matches, Loops, and Caching
Before adding a rewrite, access the old and new pages separately and confirm where each response comes from. After adding a single rule, test the old address as the positive case, then the new address and a nearby path as negative cases. If the new address also matches the same expression, or the site sends the new address back to the old one, the redirects will loop. Narrow the match or remove the rewrite; do not mask the issue with a third redirect. Check whether other rewrite rules affect either address too. Disabling and testing one rule at a time is easier to troubleshoot than changing several expressions at once.
If a redirect still appears after removing the rule, first make a new request. Then determine whether the client is still using an old configuration, the app has reused an earlier response, or the server itself is redirecting. The final address in the address bar does not show how many redirects happened along the way. If the destination redirected on its own before you added the rule, judge the rule by the response to a single request, not just by whether the final page looks the same. If diagnostic details are unavailable, remove the rewrite, reconnect, and compare the two addresses separately.
Keep only rewrite entries with a clearly defined scope. For each one, be able to explain why the old address is still needed, which requests must not be changed, who can maintain the new address, and when the rule can be removed. Do not rely on a rewrite as the sole mechanism for a production service migration. If multiple people and devices need the same result, a clear server response is easier to verify than a separate local rewrite on each device.
Test one rule against two addresses you control. If the required information is an encrypted path that is not visible, broadening the expression cannot solve the matching problem.
08 / VERIFY & RESTORE
Configuration Verification, Troubleshooting, and Rollback
The goal of configuration troubleshooting is not to make one refresh work by chance, but to find which change caused a repeatable result. Choose a request you can repeat, write down the expected hostname, policy, and outcome, then record the network, configuration file, and server in use. Compare results on the same device when possible. Do not change Wi-Fi networks, routing modes, and servers from a subscription at the same time. Note any conditions you cannot control, such as the device switching from Wi-Fi to cellular during a test.
Use Four Checks to Isolate the Problem
- Connection: Check the connection status on Home and confirm which server is selected. You can run Connectivity Test with your existing server details, but a successful test confirms only that specific test—not that every destination is reachable.
- Configuration: Check which file is active in Config, then confirm that Global Routing is set to Config. Send a new request and check whether the destination is handled by the expected rules.
- Resolution: If the rule depends on an address, compare the address and address family actually used on the current network. If the destination has no usable address, do not start by adding an address rule.
- Service: Check whether the Proxy or Direct policy is as expected, and determine whether access failed while establishing the connection, during certificate validation, or after the service returned a response.
If the same request works in Proxy but fails in Config, focus on whether an earlier rule in Config selects a different policy or the fallback behaves differently than expected. If it fails in both modes, first check the shared server, destination, and network conditions. If Direct works, it provides a useful comparison, but that alone does not identify a specific rule. After comparing modes, restore the original setting so a troubleshooting change is not left in everyday use.
Check for Unmatched Requests and Shadowed Rules
[Rule]
DOMAIN,editor.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
Use this snippet to plan three test destinations. First, an exact exception that should go Direct; second, another hostname under the same suffix that should use the proxy; and third, a hostname outside that suffix and not matched by another condition that should use the fallback. The example names illustrate rule relationships only; for a real test, use destinations that meet those conditions and are known to be reachable. If the first fails, look for an earlier match near the top of the file. If the second fails, confirm that it really shares the suffix. If the third changes, check whether you altered the fallback or another shared setting.
Two situations can look like a rule failed to match. First, the client may reuse a connection established before the edit, so the new rule never handles that existing connection. Start a new test connection. Second, the main page may load while a failed supporting request uses a completely different hostname. Identify the actual failed destination. Do not change the policy for an entire group of services just to clear an error from the interface. If you need to review request details, share only the minimum needed to identify the rule type, after removing subscription query parameters, credentials, and private addresses.
Roll Back the Smallest Change That Fits the Symptom
If only one destination is affected, remove the last exact rule you added and test the same request. If several previously working destinations fail at once, first restore the most recently changed broad rule, FINAL, or [General] setting. If changes span several sections and you did not record them clearly, select a known-good old file. After restoring it, check the routing mode and server too. The old behavior may not return if you are still using the mode from a comparison test.
Not every change comes from the config file. Switching networks may trigger a new connection under the On Demand conditions, and a remote config update may replace the content used for testing. If the issue occurs only after switching networks, test on one network first, then check whether the On Demand conditions or remote config changed. For details on connection triggers and background behavior, see On Demand and background battery usage. Don’t add routing rules to compensate for a connection restart whose cause hasn’t been identified.
Your final notes do not need to reproduce the whole configuration, but should answer four questions: what changed, which destination changed, which comparison destination stayed the same, and how to roll back. If the old configuration also fails to restore access, stop layering on changes and check the server details, device connection status, and destination service. Continue with Troubleshooting Connection Issues in the FAQ. To repeat the full process of adding details, selecting a mode, and verifying the connection, follow Quick Start in order.
Verify with a new request: the intended destination has changed, unaffected destinations remain the same, and the old file and original settings can still be restored.