Shadowrocket Config Fields and Rules Reference
From Config structure to rule matches, look up syntax by field or troubleshoot by symptom. This reference assumes you already have your own subscription or server details and does not explain how to obtain connection services.
The Getting Started Guide walks you through your first import, choosing Global Routing, and connecting. This page explains how each Config section affects the result and is best read after your first connection. If this is your first time using Shadowrocket, complete the tutorial first, then return to the relevant section to adjust your Config.
Config Structure and Activation
Distinguish Server Details, Subscriptions, and Config
Server details specify how to connect to a particular server, including the protocol, address, port, and authentication parameters. Subscribe imports and updates server entries you already have. Config controls general options, DNS resolution, request matching, and policy assignment. These serve different purposes: successfully importing a subscription does not mean its rules are in use, nor does it prove that every request will go through the currently selected server.
When checking your setup, first confirm the available server in Home, then check the Global Routing mode, and finally go to Config to see which file is active. Opening a file in the editor does not activate it; saving a copy does not necessarily select it. Troubleshooting notes should record all three states. Otherwise, the same rule may behave differently depending on how you run the test.
Section Headers and Line-by-Line Syntax
Shadowrocket Config files commonly use square brackets to mark sections. General holds shared key-value options, Rule contains rules evaluated in order, Host maps specified hostnames to addresses, and URL Rewrite holds URL rewrite expressions. Section names are part of the syntax and should not be translated. Blank lines are mainly for readability. Fields use standard ASCII punctuation; Chinese commas, full-width equals signs, and typographic quotation marks can produce unexpected parsing results.
# Config structure overview; server connection parameters omitted
[General]
dns-server = system
ipv6 = false
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
[Host]
intranet.example.com = 192.0.2.10
[URL Rewrite]
^http://legacy\.example\.com/(.*) https://www.example.com/$1 302This snippet shows only how sections are arranged; it is not a complete connection Config. The domains and addresses are for documentation purposes. In particular, a Host mapping does not create an internal server. When combining content, put each line in its existing section rather than repeatedly appending duplicate section headers. Never put rule lines in the General key-value list.
| Section | Primary purpose | What to check |
|---|---|---|
[General] | General behavior and resolution options | Key names, value types, and network conditions |
[Rule] | Request matching and policies | Rule order and fallback policy |
[Host] | Mapping a hostname to a specified address | Whether the hostname and address correspond |
[URL Rewrite] | Rewriting or redirecting request URLs | Regex scope and destination URL |
Boundaries between local edits and remote updates
If your Config comes from a remote URL, first find out what an update will replace. Fetching the remote file again may overwrite local edits; updating a server subscription and updating a Config may also be separate actions. Record long-term rules in a Config copy you control, and note their source. Rebuilding them from memory makes it difficult to tell which rules came from the original file and which were added later, especially after several updates.
Name copies by purpose, such as “Daily Config” and “Rule Testing,” rather than using ambiguous numbers. After making a copy, activate it once without changing anything and confirm that the basic connection behaves like the original. Then start editing. This lets you verify copying, switching, and rule changes separately. If you see a difference at the first step, check the file contents and selection state before adding more settings.
Your Config may contain server details, private addresses, or authentication data. When sharing a problem, include only the relevant sections and redact sensitive values while preserving commas, key names, and field order. A screenshot of the final error alone is often insufficient for diagnosis, while sharing the entire Config exposes more information than necessary. The most useful report includes a minimal redacted snippet, the expected result, and the actual match record.
When reviewing another Config example, distinguish valid section syntax from settings that suit your environment. The same rule can produce different results with different DNS settings, outbound connections, and Global Routing modes. Before adopting a line, explain its purpose; leave out anything you cannot account for. The more complex the Config, the more important it is to know which observable problem each option addresses.
General Options and DNS Resolution
Key-Value Options Are Not Routing Rules
General describes shared behavior using “key = value” syntax, unlike the comma-separated entries in Rule. Changes here can affect multiple domains, so General is rarely the best first place to fix a single website. When access fails, first determine whether the problem is DNS resolution, an unreachable address, or a rule selecting the wrong policy. Then decide whether a general option needs changing, so you do not alter requests that were already working.
dns-server = system means to use the system-provided DNS settings. It is a useful starting point for understanding the process, but it does not guarantee the same results on every network. Network changes, system settings, and the domain’s own resolution behavior can all affect the returned address. If you already have specific DNS requirements, follow the relevant technical instructions. Do not assume an address in an example is suitable for your network.
[General]
dns-server = system
ipv6 = false
skip-proxy = 127.0.0.1, localhostipv6 = false illustrates a Boolean value; it does not mean everyone should disable IPv6. Whether to enable it depends on the current network, server capabilities, and destination address. If disabling it fixes access, that only shows that the request path changed; it does not prove the cause. Keep DNS records from before and after the change to tell whether an unreachable IPv6 address was returned or another setting changed when the connection restarted.
When Domain and Address Information Becomes Available
When an app makes a request, the client may not have the full URL, domain, and destination address at the same time. Some requests connect using a domain; others connect directly to an address. Existing connections may also continue using cached results. Domain and IP rules depend on different information, so check what the request record actually shows before deciding whether a particular match can apply.
An IP rule may need a domain lookup before it can be evaluated. Adding no-resolve to a rule prevents the client from resolving a domain solely to check that IP rule; it does not disable DNS throughout the app. If a request already uses an IP address, the existing address may still be matched. This distinction helps avoid unnecessary lookups and explains why the same IP rule can behave differently for different requests.
[Rule]
DOMAIN,portal.example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
FINAL,PROXYThe example handles an explicit domain first, checks whether an available address falls within a documentation-only range second, and applies the fallback last. If a request has only a domain and does not match the first rule, the IP rule with no-resolve will not trigger an additional lookup just for itself. Do not assume that it must match simply because the domain eventually resolves to an address in that range. Use the request details and match record to verify.
skip-proxy and Request Routing
skip-proxy lists exceptions at the system proxy layer; it is not interchangeable with DIRECT in Rule. Traffic can reach the client through different paths, and system proxy exceptions are no substitute for a complete rule design. For traffic that needs a verifiable routing result, define the conditions explicitly in Rule and confirm that the traffic is actually on a path the client can handle.
For internal domains, first confirm that the system network provides the required DNS resolution. Even if a rule selects DIRECT, the system still needs the correct address for the host. Even if Host supplies an address, the device still needs a reachable route to it. Resolution, policy, and connectivity are related but distinct steps; changing one does not replace the others.
DNS results may also be cached by the app, system, or client. After changing DNS settings, close the current test page and start a new request; use the relevant in-app cache-clearing tool if needed. Do not clear caches, change servers, and adjust rules all at once. Otherwise, even if access returns, you will not know which change helped. At minimum, record the network type, destination host, resolved address, and actual policy when retesting.
If only some domains fail, compare them with domains that work instead of immediately replacing all general options. Check whether the failing domains return an address, whether that address has changed, and whether other destinations using the same policy are reachable. DNS issues often appear after a network change. Comparing before-and-after states can show whether network conditions changed or a different Config was selected.
DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD
Exact Hostnames and Suffix Scope
DOMAIN matches one exact hostname. With api.example.com as the condition, the rule applies to that host; it does not automatically include www.example.com or deeper subdomains. Do not include a protocol, port, slash, or URL path in the condition. Ordinary domain rules cannot distinguish pages on the same host because their domains are identical.
DOMAIN-SUFFIX matches the specified domain and its subdomains. With example.com as the condition, it can match the domain itself as well as subdomains such as api.example.com. It is not an arbitrary string-ending match and should not include notexample.com. Do not add a leading asterisk or paste a browser-style URL directly into the condition.
[Rule]
DOMAIN,accounts.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTIn this set of rules, the account host matches the exact exception first; the suffix rule handles other hosts under example.com. If the suffix rule comes first, the account host will match it and the exact exception below will never run. An exact match has narrower scope, but it does not automatically take priority over file order. Place it above broader rules explicitly.
Avoiding Overbroad Keyword Matches
DOMAIN-KEYWORD checks whether a domain contains the specified keyword. It can be useful when the same string needs to match across multiple domains, but it does not understand organizational ownership or word boundaries. A short keyword may match many unrelated hosts. If you know just one or a few domains, prefer DOMAIN or DOMAIN-SUFFIX so the scope is easy to explain and verify.
[Rule]
DOMAIN-SUFFIX,example.com,DIRECT
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECTThis example keeps the example.com exception first, then sends other domains containing the string example to PROXY. The order illustrates the semantics; it is not a general recommendation. Before using a keyword, list the hosts you want and do not want to match from actual request records. Check each one rather than stopping after a single page loads successfully.
| Type | Example condition | Scope |
|---|---|---|
DOMAIN | api.example.com | Matches only the exact hostname |
DOMAIN-SUFFIX | example.com | The domain and its subdomains |
DOMAIN-KEYWORD | example | The domain contains this string |
Pages Load Resources from Multiple Hosts
The host shown in the browser’s address bar may not cover every destination loaded by a page. Images, fonts, sign-in checks, APIs, and video segments may come from different domains. If the main page works but some content fails, check the hosts used by the missing resources before adding rules. Sending an entire top-level domain range through one policy may be easy, but it broadens the impact and can hide the condition that actually needs attention.
A service may also use external storage or content delivery hosts that are not subdomains of its main site. Confirm the relationship using actual request records and service documentation; do not infer ownership from similar spelling. Changing the policy for a shared public resource domain may affect other apps. If necessary, add a more precise exception and explain why the main site’s suffix alone is not sufficient.
Some requests connect directly to an address with no usable hostname. Other domains resolve through aliases, while rule records still show the original request hostname. Do not assume a domain rule must match an alias just because a DNS lookup showed it. Use the destination fields in the client’s records; if only an address appears, check IP rules and whether domain information is available.
When testing domain rules, start with a temporary exact-match rule for a single host. After confirming the match, expand it to a suffix rule and test one subdomain and one unrelated domain. This verifies syntax, order, and scope separately. Remove the temporary rule when finished so a forgotten exception does not remain hidden above a broader rule.
When maintaining a domain list, note the real purpose of each rule instead of accumulating unexplained suffixes. Duplicate rules do not improve reliability; identical conditions with different policies are especially misleading. Keep the effective first entry and check whether later duplicates are obsolete. After editing, retest different kinds of requests, such as sign-in, static resources, and APIs.
IP-CIDR, GEOIP, and USER-AGENT
Address Ranges and Prefix Length
IP-CIDR represents an IPv4 range using a network address and prefix length. A longer prefix usually covers a smaller range; a single address can use a 32-bit prefix. Before adding a condition, decide whether you need one host or a whole subnet. Do not widen the scope just because two addresses share the same initial octets. For a local network, check the address range actually assigned on the current network to avoid routing unrelated remote addresses through DIRECT.
[Rule]
IP-CIDR,192.0.2.10/32,DIRECT,no-resolve
IP-CIDR,198.51.100.0/24,PROXY,no-resolve
IP-CIDR6,2001:db8::/32,DIRECT,no-resolve
FINAL,PROXYAll addresses above are for documentation only, not usable service addresses. The first rule selects one IPv4 address, the second an IPv4 range, and the third illustrates IPv6 prefix syntax. IP-CIDR6 is for IPv6 ranges; do not put a colon-separated address in IP-CIDR. A prefix represents a set of addresses, not a port range, and cannot distinguish websites hosted on the same server.
If multiple domains share an address, an IP rule may affect them all. When the target host is known, domain rules are usually the better starting point; use a subnet rule when the service is actually managed by address. Conversely, if the target is a fixed internal device and the request connects by address, a domain rule cannot replace an IP rule. Choose based on how the service is identified, not on which syntax looks shorter.
GEOIP Classifies Addresses, Not Websites
GEOIP checks the region classification in an address database, as in GEOIP,CN,DIRECT. It describes the target address’s classification, not the domain’s registration location or service provider’s location. Content delivery can cause a site to resolve to different addresses on different networks, and the database may not reflect current usage. Treat regional rules as broad supplementary conditions.
[Rule]
DOMAIN,api.example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXYThis example sets a policy for a specific API first, then uses the region condition for other requests. If GEOIP comes first, an API address classified in that region may match it before the exact domain exception can run. Rules are evaluated in order; a more specific domain condition later in the file does not automatically take priority. If routing is unexpected, check the match position before questioning the address database.
GEOIP evaluation may require resolving the destination domain. Add no-resolve based on whether you want this condition to trigger a lookup. With it, a request that has only a domain and no available address may continue to later rules; without it, an additional lookup may occur. This is a behavioral trade-off, not a universally correct setting. Verify it against actual request records.
USER-AGENT Visibility Limits
USER-AGENT matches User-Agent information visible in a request; it is not a way to route by app identity. Different apps may send the same value, and one app may change its value by request type. Encrypted connections do not automatically expose every HTTP header, so do not expect this rule to identify all app traffic or act as a system-wide process selector.
[Rule]
USER-AGENT,ExampleClient*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTExampleClient* illustrates the syntax; use an actual request identifier you can verify. Guessing a User-Agent from an app’s name often fails because the product name and request header may differ. If the request record does not show the relevant information, use an observable domain or address condition instead. Do not try to compensate for missing information by continually widening a wildcard.
Access control should not rely on USER-AGENT alone. This field is request metadata, not a strong authentication credential; the same destination may carry different values across requests. If you need to block a specific host, a domain condition is easier to verify. To distinguish services on the same host, first confirm that the client can see information that represents the difference, then decide whether a rule can handle it.
When testing IP and metadata rules, cover both existing and new connections, and requests made by domain and by address. A single match proves only that this request met the condition; it does not establish that all similar traffic behaves the same way. If a record lacks a key field, note that the evidence is insufficient and keep rules focused on observable information rather than turning an accidental result into a broad default.
PROXY, DIRECT, REJECT, and Rule Priority
Check the Global Routing Mode First
The Config, Proxy, and Direct options in Global Routing correspond to configuration-based, proxy, and direct modes. To investigate individual Rule matches, select Config and confirm which Config file is active. Proxy and Direct apply their respective global modes; their results do not prove that an ordinary routing rule is correct. The interface option Proxy and the rule keyword PROXY differ in capitalization and operate at different levels.
| Level | Name | Meaning and what to check |
|---|---|---|
| Global Routing | Config | Test rule matches using the active Config |
| Global Routing | Proxy / Direct | Global mode; not a Rule entry |
| Rule policy | PROXY | Use the currently selected proxy |
| Rule policy | DIRECT | Connect directly over the local network |
| Rule policy | REJECT | Reject matching requests |
PROXY does not define a server in the rule; it refers to the currently available proxy selection. If the server details are incorrect, authentication fails, or the server is unreachable, a request can fail even when the rule matches correctly. DIRECT does not bypass all network conditions on the device; the current network, DNS, and destination service still matter. REJECT explicitly blocks a request and should not be used as a default way to probe an unknown issue.
First Match and Explicit Exceptions
Rule entries are generally evaluated from top to bottom, and the first matching condition determines the policy. Rules are not reordered by domain length, type name, or when they were written. A useful structure is “exact exceptions, service domains, IP rules, final fallback,” but this is a way to make the logic easier to follow, not a fixed list to copy. Be able to explain why each rule appears where it does.
[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN,blocked.example.net,REJECT
GEOIP,CN,DIRECT
FINAL,PROXYOnce the sign-in host matches the first rule, the example.com suffix rule no longer determines its policy. Another example.com subdomain continues to the second rule. The explicitly listed blocked target is handled by the third rule; only other requests reach the region check. To review a Config, trace a specific host from the first line downward instead of focusing on one line that looks relevant.
If a broad DIRECT rule above the third rule also includes its REJECT target, the rejection may never run. Repeating the same REJECT entry will not fix this conflict; move the rule or narrow the earlier condition. Before removing a rule that appears ineffective, check whether it is intentionally retained as documentation. If it truly has no effect, a comment explaining why is clearer than conflicting active entries.
FINAL Is a Fallback, Not an Automatic Fix
FINAL does not require a domain condition. Its basic forms are FINAL,PROXY and FINAL,DIRECT. It catches requests that did not match earlier rules and belongs at the end. Placing FINAL in the middle prevents later ordinary rules from getting their expected chance to run. When checking a Config, search for FINAL; one clearly defined final policy is usually enough. Do not use multiple fallbacks to express different purposes.
Choose a fallback based on your actual needs and existing connection setup. FINAL set to PROXY sends otherwise uncategorized requests to the proxy selection; FINAL set to DIRECT sends them over the current network. Neither guarantees that the destination is reachable. If one service fails, add a specific exception supported by evidence rather than switching the entire fallback back and forth to see what happens.
# Place exact exceptions before broader rules that include them
[Rule]
DOMAIN,health.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTWhen testing this example, check at least a health-check host, another example.com subdomain, and a completely unrelated domain. These three cases verify the exception, suffix rule, and fallback respectively. Testing only the first case may not reveal an accidental change to FINAL; testing only the main site may not reveal that the exact exception is being overridden. Test rule boundaries, not just one successful path.
On Demand controls whether a connection starts under the relevant network conditions; it does not replace Rule when choosing a request policy. After an automatic connection starts, still check Global Routing and Config. If results change after switching networks, check whether the connection was restarted, whether the Config is the same, and whether DNS changed. On Demand being enabled does not prove that every request uses the intended outbound route.
Evaluate policy matches separately from service success. A match record confirms classification logic; a response from the destination confirms that the current path works. Both matter. When a request fails, first determine whether it used the wrong policy or the right policy but could not connect. For more first-connection questions, see FAQs so you do not mistake a purchase or server authentication issue for a rule-priority problem.
What Host Mapping and URL Rewrite Can and Cannot Do
Host Changes Address Mapping, Not Website Identity
Host provides a static address mapping for a specified hostname, typically in a controlled environment where the user already knows the destination address. It cannot discover internal devices or guarantee that an address is reachable. Before adding a mapping, obtain the correct address and confirm that the host serves the intended service there. Entering a random reachable address sends requests to the wrong destination; it is not a way to fix DNS resolution.
[Host]
portal.example.com = 192.0.2.20
files.example.com = 192.0.2.21
[Rule]
DOMAIN,portal.example.com,DIRECT
DOMAIN,files.example.com,DIRECT
FINAL,PROXYHost specifies an address; Rule specifies a policy. They describe different steps. The address here uses a documentation-only range and must be replaced with a valid value from your own environment. If the target address is reachable only on a particular network, the mapping may remain in place but fail when the device leaves that network. Check the route to the address rather than adding more mappings for the same hostname.
With HTTPS, the original hostname still participates in website identity verification. Mapping a domain to another address does not make the certificate valid or change the hostname in the request to that address. If the certificate name does not match, check the mapping target and server configuration; do not treat disabling verification as a normal fix. Review static mappings promptly when the destination service moves.
Host mappings and caches can also affect what you observe. If requests still use the old address after a change, end existing connections first and check for app-level caching. Evaluate the mapping only after confirming that a new request uses it. To restore the original resolution, remove the test mapping and make a new request; this is easier to track than adding competing values for the same host.
URL Rewrite Matches URL Expressions
URL Rewrite uses regular expressions to identify request URLs and apply a rewrite or redirect. It is not the same as domain-based routing: domain rules select a policy, while rewrite rules change the target expression. To send a host directly, you do not need URL Rewrite. Add this section only for a controlled URL migration, path adjustment, or similar need.
[URL Rewrite]
^http://legacy\.example\.com/(.*) https://www.example.com/$1 302This example redirects an HTTP URL from an old host to a new host and preserves the captured remainder. The initial caret anchors the match at the start; backslashes make the dots in the domain literal; parentheses create a capture group; and the dollar sign followed by a number in the target refers to that group. The final 302 indicates a temporary redirect. This demonstrates syntax only; the destination domain is not a usable service.
Omitting the start anchor or failing to escape dots broadens the regex match. A dot in a regular expression usually means any character, not a literal domain separator. Before editing, test several similar URLs: the intended old host should match, other hosts should not, and URLs already on the new host should not match again. A narrow scope makes it easier to confirm that the rewrite affects only the intended requests.
Redirects, Encryption, and Loop Checks
Which URL information the client can process depends on the request path and what is visible through encryption. Do not assume URL Rewrite can read any HTTPS path. If a tunnel exposes only the hostname, an expression based on the full path may not have the information it needs. Validate with a visible, controlled request first; do not broaden certificate trust or inspection scope just to address a path issue.
After a redirect, the app must make another request to the new destination, which must also be reachable and handled by the current routing Config. A correct rule for the old destination does not mean the new one uses the same policy. If the new host redirects back to the old one, a loop forms; a browser may report too many redirects. Check the source and destination of each hop to see whether server behavior and local rules are interacting.
Clients may cache permanent redirects. During testing, a controllable temporary redirect is usually easier to validate; decide on the final behavior once confirmed and based on the service’s requirements. Even after removing a local rule, an app cache may temporarily preserve the result. Retest with a new request and record the redirect chain instead of judging whether the rule is still active from the final address in the address bar.
Query parameters may contain authentication or business state. Do not discard or combine them without understanding their structure. Check against specific samples whether the capture expression preserves the query string; special characters in paths can also require different escaping. For sign-in, payment, or form submission flows, follow the service’s own redirect design rather than generalizing from a simple GET request.
Combining, Merging, and Maintaining Rules
Start with the Smallest Rule Set You Can Explain
Before building a rule set, write the requirement in plain language, for example: “Connect the account host directly, use the current proxy for other service subdomains, and keep all remaining requests on a direct connection.” Then translate each part into a condition. This helps establish whether a new rule is necessary and gives you a clear way back to the requirement if testing fails, instead of masking conflicts with broader matches.
[Rule]
# Account host exception
DOMAIN,accounts.example.com,DIRECT
# Service domains
DOMAIN-SUFFIX,example.com,PROXY
# User-confirmed blocked targets
DOMAIN,blocked.example.net,REJECT
# Other requests
FINAL,DIRECTThis intentionally small example is easy to check line by line. It contains neither server addresses nor subscription content and assumes you already have usable connection details. When adding a service, confirm the target host first, then choose an exact or suffix condition. Do not add a long, unchecked list of domains just because one page fails; later, it will be difficult to tell which rules actually mattered.
Resolve Conflicts When Merging Rules
Merging two Config files is more than concatenating their text. Identify each file’s sections, move like content into the corresponding sections, then review rule order and FINAL. For conflicting values under the same General key, different addresses for the same Host entry, or different policies for the same Rule condition, decide manually what to keep rather than relying on ambiguous duplicate behavior.
Exact domains can also conflict with suffix rules. One file may send all of example.com through PROXY while another sends a specific API under it through DIRECT. These are not simple duplicate entries; put the exact exception before the broader rule. When merging, search all entries around the same parent domain and check for an earlier suffix or keyword rule that may already cover it.
# Merged order: exceptions first, broader conditions afterward
[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXYIf the original file contains custom policy names, confirm that the target Config defines those names and uses the same spelling and capitalization. This page uses PROXY, DIRECT, and REJECT to explain basic behavior; that does not mean any unfamiliar policy name will work as written. For an unknown reference, first find out which server selection or policy group it points to, then decide whether to keep it.
Track Changes and Update Boundaries
For each change, record the target, edited lines, and test result. Put comments on separate lines and note the service purpose and reason for an exception; lengthy explanations are unnecessary. Mark temporary troubleshooting rules with conditions for removing them, or they may be forgotten after several tests and become hidden priorities. When reviewing the rules, also check that comments still match the active policies. Outdated comments can make a Config harder to maintain than no explanation at all.
Before updating a remote Config, back up your local copy and compare key sections rather than just checking whether the file downloaded successfully. The source may change the fallback, add a broad rule, or adjust DNS options, all of which can affect local exceptions. When merging local changes again, place them according to their meaning. Pasting an old exception at the end may leave it after FINAL, where it cannot take effect.
Subscription updates primarily affect your existing server entries; they are not a universal way to sync rules. If the proxy path behaves differently after an update, check that the selected server is still valid, authentication parameters have not changed, and old entries were not replaced. If a rule still matches PROXY but now points to a different connection selection, service behavior can change. Adjusting domain rule order will not fix that.
Keep Config backups and server credentials in separate storage scopes. An exported file may contain connection parameters or depend on a separately saved server list; the same filename after moving to a new device does not prove that everything is included. See Backing Up Config and Restoring It on a New iPhone for preparation and recovery steps, and verify a restore while the old device is still available.
Review and trim growing rule sets periodically. For entries that never match, have no clear purpose, or are already covered by a broader condition, disable them in a test copy first and observe the result before deciding whether to remove them. The goal is not the fewest lines; every active rule should have a clear reason to exist. Keeping normal traffic stable is easier than adding every conceivable rule type.
Manage protocol connection parameters separately from routing policies. For example, WireGuard keys and addresses affect whether a connection can be established, while DOMAIN-SUFFIX determines which destinations use that proxy selection. These are different layers. See How to Fill In WireGuard Config Fields for field details. Do not broaden domain matching to try to fix an authentication error.
Rule Validation, Troubleshooting, and Recovery
Set Up Repeatable Test Conditions
A useful test has a specific target host, expected policy, fixed network, and clearly identified Config state. First select Config mode, record the active file and server, then make a new request. Do not update subscriptions or switch networks during the test. If conditions keep changing, even an occasional success cannot show that the rule change caused it, and the result will not be useful for future maintenance.
For each change, test three kinds of cases: a target that should match, a target that should take an exception, and a target that should be unaffected. Record the rule, policy, and service result for each. For a new suffix rule, test the parent domain, a subdomain, and a similar domain outside the suffix. For a new IP rule, test one address inside and one outside the range rather than validating only a successful case.
| Observed symptom | Check first | Next step |
|---|---|---|
| Expected rule did not match | Active file, mode, request fields | Check earlier broad rules and use a new request |
| PROXY matched, but the request failed | Server connection and authentication | Separate outbound routing issues from destination service issues |
| DIRECT matched, but the request failed | Local DNS resolution and network path | Check the returned address and whether it is reachable |
| Main page works, but resources fail | Actual hosts serving the resources | Check each dependent request |
| Result unchanged after editing | Cache and existing long-lived connections | Make a new request and confirm the active file |
Distinguish a Missing Match from a Failure After a Match
If no rule matches, first check whether the target actually has the information the rule needs. A domain condition cannot match a request that has only an address, and USER-AGENT cannot match an invisible header. Next, scan Rule from the top for an earlier suffix, keyword, region condition, or FINAL. Finally, check ASCII punctuation, policy spelling, and whether the entry is in the correct section.
If a request matches but still fails, stop moving rules without evidence. For a PROXY branch, check whether the selected server can connect, whether authentication details are still valid, and whether the destination service is reachable. For DIRECT, check whether the local network can reach the resolved address. If only one target fails, compare its differences first; if all requests using the same policy fail, check the connection conditions they share.
Connectivity Test can provide a result under specific test conditions, but it cannot replace testing each service request. A responsive test target does not guarantee that a sign-in API, video resource, or request using another protocol will work. Treat the result as evidence that helps narrow the issue and compare it with the actual failed request. One reading cannot validate an entire Config.
Account for Caches, Long-Lived Connections, and Network Changes
A Config change does not necessarily cause every existing connection to restart immediately with the new policy. Browsers may reuse connections, apps may transfer data in the background, and media may keep playing over an existing session. For validation, end the relevant session and make a new request; restart the client connection if necessary. A page that keeps playing shows only that the old connection still works, not that new connections use the updated rule.
Switching from Wi-Fi to cellular can change DNS servers, reachable addresses, and connection state at the same time. An internal host that was reachable on the original network may fail after the switch without any rule error. Check whether On Demand established a connection, whether Global Routing kept the same mode, and whether the target depends on the original network path before planning separate Configs for different networks.
Data shows traffic volume within the recorded scope; it does not directly prove a rule match. Traffic on a server shows only that the server participated in some transfer, not that the current test target used it. A cached response may also produce little new traffic. See Understanding Traffic Statistics for how to interpret the figures. Validate routing against individual requests.
Minimize Reproductions and Roll Back Safely
For a complex issue, simplify a test copy step by step: keep the necessary General options, one target rule, and one FINAL, and temporarily remove unrelated Host and URL Rewrite entries. Repeat the same test after each group of changes and compare the result. Do not clear every section in your everyday Config; without a baseline, it is difficult to restore behavior that was working before.
# Rule section for isolating a single target; not a complete connection Config
[Rule]
DOMAIN,api.example.com,PROXY
FINAL,DIRECTIf the minimal rules match as expected, restore the original content one group at a time to find where the behavior first changes. If the minimal rules still do not match, recheck activation and request fields instead of merging more rules. Changing one variable at a time helps distinguish an inactive file, an earlier rule taking precedence, and a policy-path issue, reducing repeated trial and error.
If you need further help, provide the relevant redacted sections, actual host, matched policy, network conditions, and steps to reproduce. Do not share full subscription URLs, keys, or authentication fields. If you cannot narrow down the issue, restore a verified backup and confirm that the original traffic works before scheduling another test. For importing and first-time authorization, return to the Getting Started Guide. For purchase verification and restoring access to a previous purchase, see Restore Purchases.