OFFICIAL MANUAL · CONFIGURATION

Shadowrocket Rules Manual
Configuration Structure and Match Order

First confirm that the configuration is being used for routing. Then check the match criteria, rule order, and final policy. Correct rule syntax does not guarantee that a request will match that rule.

This page is a reference manual for in-depth lookup. For your first setup, complete the quick start guide first, then use the sections here to adjust your configuration. Connection instructions assume you already have your own subscription or server details. The one-time app purchase does not include a connectivity plan.

01 · FILE STRUCTURE

Configuration File Structure: Know the Sections

A configuration file and a subscription are different things

A configuration file describes how requests are handled. A subscription is primarily used to import and maintain your existing server entries. Both can contribute to a connection, but they are not interchangeable. A successful subscription update only confirms that its contents were read; it does not prove that the active rules are correct. Likewise, a configuration file being saved does not prove that its referenced proxies are available. Before troubleshooting, check each separately so you do not mistake a server parameter issue for a rule exception.

In Config, check which configuration is selected, then open it in the appropriate editor. To experiment, make a copy, give it a clear name, and keep the original. Changes to a copy usually have no effect unless that copy is selected. If you edit the active file, reload it as prompted by the app after saving. To verify the change, make a new request instead of relying on a connection established before the edit.

Square brackets define a setting's scope

Shadowrocket text configurations are organized under section headers. [General] contains general settings, [Rule] contains routing rules, [Host] contains hostname mappings, and [URL Rewrite] contains URL rewrite rules. Sections are not decorative: the same line can mean different things in different sections. When copying a snippet, check where it belongs as well as its contents. A keyword appearing somewhere in the file does not mean the setting is active.

[General]
dns-server = system

[Rule]
DOMAIN,example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This example shows structure only. The first rule handles the root domain exactly, the second handles other domains with the same suffix, and the last handles remaining requests. dns-server = system uses the system DNS settings; it does not guarantee the same DNS results in every environment. Saving the example does not select a server, authorize a connection, or complete all network settings. Check those separately in the app.

Keep configuration changes small and traceable

When reading a long file, start with the section headers, then find the passage relevant to the issue. Repeated sections, duplicate fallback rules, and temporary entries scattered at the end of the file make it harder to diagnose. Keep related local exceptions together, with a separate comment explaining each one. Comments should explain why a rule is needed, not restate the rule. Do not include real subscription URLs or authentication details in comments you plan to share.

Read a configuration before importing it; do not judge suitability by its filename. Check the final policy, DNS settings, host mappings, and rewrite section, then look for policy names that do not exist in your current setup. A configuration with many rules may still be designed for a different server setup. If you encounter an unfamiliar option, leave it unchanged and check whether the app supports it. Do not copy setting names from another format into this file.

Manage automatically updated content separately from content you maintain manually. If an update to the configuration source overwrites local edits, your changes may disappear next time. First confirm whether the update applies to a subscription or the entire configuration, then decide where local exceptions belong. If you are unsure what will be overwritten, keep a separate copy and record the differences. This is easier to restore and makes it easier to tell whether an issue came from an update or a local change.

Some code blocks below include section headers; others contain rule lines only. Add rule-only snippets to an existing [Rule] section rather than creating a new one for every example. If you need to recheck the purchase and first launch, see the App Store authenticity guide. This manual keeps obtaining the app separate from configuring network traffic.

02 · GLOBAL ROUTING

Global Routing: Determine Whether Rules Apply

Check Config, Proxy, and Direct first

To route traffic according to a configuration file, set Global Routing to Config. Proxy and Direct are global handling modes, not two ordinary rules to add to a configuration. If the current mode is Proxy, changing a domain rule cannot prove that routing in Config is correct. If the mode is Direct, successful access to a destination does not show that a proxy server handled the request. Check the mode first when troubleshooting.

Interface optionHow it handles trafficWhat to check
ConfigRoutes traffic according to the rules in the active configuration.Check rule matching and policy selection.
ProxyGlobal proxy mode.Check whether the proxy path is available.
DirectGlobal direct mode.Check how a direct connection behaves.

The table summarizes the main purpose of each mode; it does not mean that all other configuration settings are completely replaced. DNS, existing connections, and the network behavior of individual apps may still affect what you observe. Switching modes is a way to compare behavior, not a test that proves any part of the setup is working perfectly. During testing, note the active mode and selected configuration, then restore the intended settings when done. Otherwise, later changes may be based on the wrong assumptions.

Assess mode, rules, and server details separately

Break troubleshooting into three steps: check whether traffic is being routed through the configuration, identify which rule matches the request, then check whether the connection resources required by that policy are available. A rule selecting PROXY specifies how to handle traffic; it does not supply a server address, port, or authentication details. If your subscription has no usable entries, even a precise domain rule cannot provide the connection parameters. Check your own server details before considering additional exceptions.

Do not confuse Proxy in the interface with PROXY in a rule. The former is a Global Routing option; the latter is a policy keyword in configuration text. Both relate to proxy traffic, but at different levels. The same distinction applies to Direct in the interface and DIRECT in a rule. Keep the keywords uppercase when editing so they are easier to distinguish from mode names.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This rule is intended to send requests matching the specified domain suffix through PROXY and all other requests through DIRECT, provided Config is active. To test it, check one request that should match and another that should not. A site loading successfully does not tell you whether the rule matched, a global mode overrode the expected behavior, or the site was reachable directly anyway.

Use controlled comparisons to narrow down the issue

If a connection works in Proxy but fails in Config, first check the file selected in Config, policy references, and rule order. The difference shows that the two modes handle traffic differently, but does not prove the domain rule is wrong. A host mapping, DNS setting, or earlier REJECT rule could also explain it. If both modes fail, check your server details and basic network connectivity before adding more rules.

If Direct works but Proxy fails, troubleshoot the proxy path instead of immediately changing the entire domain suffix to DIRECT. Temporarily switching to direct can help with comparison, but it also changes the request path and may only bypass the original issue. Note whether the failure occurs during connection setup, name resolution, or a later request stage before deciding what to change. Change one condition at a time so you can interpret the result.

After switching modes, reopen the destination or repeat the action to generate a new request. If necessary, end the existing connection before testing. Long-lived connections may continue using the handling mode in effect when they were established, and a cached page can make it seem as if a new network request just occurred. Choose an action that clearly generates a request, then check the connection details visible in the app. For step-by-step instructions, see Global Routing in the guide.

03 · DOMAIN MATCHING

Domain Rules: Exact Matches and Wider Scopes

DOMAIN: match one exact hostname

DOMAIN matches an exact domain name. A rule for example.com matches that hostname only; it does not automatically include all subdomains. Exact rules are usually easier to verify when you need to handle one specific host. To cover both the root domain and subdomains, consider a suffix rule instead. Do not include a scheme, path, or query string in an exact domain parameter; those are not part of the hostname.

DOMAIN,example.com,DIRECT
DOMAIN,www.example.com,PROXY
DOMAIN,api.example.com,PROXY

These three lines each handle one complete hostname. The second does not match the first or automatically cover the third. A website may use separate hosts for pages, sign-in, images, and APIs, while the browser address bar shows only one of them. If the homepage works but sign-in fails, check the hostname of the failed request before adding a rule. Do not assume the entire service is covered just because the root domain appears in the address bar.

DOMAIN-SUFFIX: match a suffix at a domain boundary

DOMAIN-SUFFIX,example.com,PROXY matches the domain suffix, usually covering the root domain and its subdomains, such as www.example.com. It is not a substring search: notexample.com does not match just because its text ends similarly. Check domain label boundaries rather than treating a suffix rule as a search across the entire URL.

A common mistake is assuming that *.example.com is required for a suffix rule. Writing example.com directly expresses the suffix; no wildcard is needed. Do not add a trailing slash to the rule parameter either. When copying a URL, extract the hostname first by removing the scheme, port, path, and query string. Then decide whether an exact or suffix rule is appropriate.

DOMAIN-KEYWORD: wider scope, check for unintended matches

DOMAIN-KEYWORD checks whether a domain contains a specified string. It does not respect full domain label boundaries, so its scope can be harder to predict than a suffix rule. Unless you need to match multiple domains by a shared string, prefer a list of exact hostnames or a clearly defined suffix. Shorter keywords are more likely to match unrelated requests and make it harder to explain why a particular host uses the proxy path.

DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,REJECT
FINAL,DIRECT

In this order, the exact hostname uses DIRECT first. Other requests under the same suffix then use PROXY. Only domains containing the keyword that were not handled by the first two rules may reach REJECT. This example illustrates the difference in scope; it is not a recommendation to reject every name matching a broad keyword. Moving the third rule earlier could prevent intended exceptions from being considered.

TypeWhat it matchesCommon boundary
DOMAINThe full hostname.Does not automatically include subdomains.
DOMAIN-SUFFIXThe root domain and matching subdomain suffixes.Does not match URL paths.
DOMAIN-KEYWORDA string within the domain.May match unrelated hostnames.

Domain rules depend on the client having hostname information available for matching. If a request connects directly to an IP address, do not assume the original hostname can always be inferred. Conversely, a domain resolving to multiple addresses does not mean you need to write a rule for every address. Choose a rule based on the actual request: use domain rules when the hostname can be identified reliably, and address rules when you specifically need to handle an IP range.

After adding a domain rule, check how it handles the root domain, a subdomain, and a similar but unrelated domain. You can reason through these cases first; the examples do not need to be real, reachable services. For a detailed explanation of the basic syntax, see DOMAIN, DOMAIN-SUFFIX, and other rule types explained. The next section covers how to reason about overlapping address and domain rules.

04 · ADDRESS AND REQUEST

IP Addresses and Request Attributes: Check What Is Visible

IP-CIDR and IP-CIDR6 define address ranges

IP-CIDR is for IPv4 ranges and IP-CIDR6 is for IPv6 ranges. The number after the slash is the prefix length, not a port or a wildcard count. Use /32 for a single IPv4 address and /128 for a single IPv6 address. A larger range affects more addresses. Do not put an entire neighboring range under the same policy just because one address failed to connect.

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

These documentation-only addresses do not represent real servers. The first line is an exception for one exact address; the second covers a wider range. Their order determines whether the exception can take effect. The IPv6 example shows syntax for another address family and does not replace an IPv4 rule. If a real destination may resolve to either address family, check how each is handled rather than assuming one address family represents the entire request.

no-resolve controls additional lookups for rule matching

When an address rule is evaluated against a domain request, an address may need to be obtained first. no-resolve prevents a DNS lookup from being triggered solely for this rule's match. If an address is already available, interpret the result according to the actual processing flow. This option does not disable DNS throughout the client or guarantee that no other resolution path will be used. Treating it as a general DNS troubleshooting switch can lead you away from the real issue.

For services you want to route consistently by domain, domain rules are usually the better way to express that intent. Use address rules when you need to handle a specific IP range. The same IP may host multiple domains, while a single host may resolve to different addresses depending on the network, resolver, or time. Turning one DNS result into a permanent rule may miss later address changes or affect other services on a shared address.

GEOIP classifies addresses; it does not identify websites

GEOIP,CN,DIRECT selects a policy based on a geographic classification in an IP address database. It checks address attribution, not site ownership or page content. A service using distributed infrastructure may have a domain identity that does not correspond to the region assigned to its access address. Databases are also updated and have classification boundaries, so a regional match is not a permanent statement about where a service is deployed.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

This example assigns a route to specified domains first, uses address classification for other requests, and then applies the fallback. This puts domain-specific intent ahead of a broader address-based check. If GEOIP is moved earlier, a domain resolving to an address in the relevant range may be handled before its domain rule gets a chance. No rule type is inherently more important; the first rule whose conditions match takes effect.

USER-AGENT depends on request visibility

USER-AGENT matches observable request-header information. It can be used when the relevant request data is available, but it is not a reliable way to identify every app. Different apps may use the same identifier, and one app may use different identifiers across requests. In particular, ordinary forwarding of encrypted traffic does not expose its HTTP headers. If the field is not visible, the rule cannot infer its value from an app's name.

USER-AGENT,ExampleClient*,DIRECT

This line illustrates the rule type and wildcard syntax; it does not mean that the example program is installed on your device. Do not change device security settings just to make the example match, and do not use USER-AGENT instead of an explicit domain rule when one will do. If the rule seems ineffective, first check whether the actual request contains a visible field that matches your rule, then check rule order. Adding similar rules will not help if the field cannot be observed.

Interpret address, region, and request-attribute rules in light of what is actually visible. If a log shows only one destination address, first determine whether it is the address in the direct request, a DNS result, or the proxy server address; these are different things. Mistaking the outer connection to a server for the destination website's address can invalidate the entire routing analysis. If you are unsure, compare against a minimal domain rule, then add address conditions one at a time.

05 · POLICIES AND FINAL

Policies and FINAL: Separate Conditions from Actions

Rules define what matches; policies define what happens

A typical domain rule consists of a type, a match value, and a policy. In DOMAIN-SUFFIX,example.com,PROXY, the first two fields define the condition and the last specifies how to handle a match. Changing the last field does not change the match scope. Replacing PROXY with DIRECT selects the same domains but changes their route. Understanding this distinction helps prevent fixing a policy issue by changing the domain scope.

PolicyActionDoes not mean
PROXYUse the proxy route.The server is available.
DIRECTConnect directly to the destination.Access will succeed.
REJECTReject the matching request.A connection optimization option.

Check which connection entry PROXY uses in the active configuration and app selection. If the configuration also has custom policy names, confirm that they are defined and that their members fit your current setup. A name that sounds like a proxy does not guarantee that it points to the currently selected server. When copying rules, do not keep custom names from the source file without checking; references may no longer match the actual configuration.

DIRECT selects a route; it does not guarantee success

DIRECT sends matching requests over a direct connection, which still depends on the local network, destination service, and resolution results. If a request still fails after changing its rule to DIRECT, continue troubleshooting the direct path instead of assuming the rule did not match. Conversely, successful direct access does not show that authentication, certificates, or transport settings on the original proxy path are correct. Policy selection and network reachability are separate questions; verify each with logs and an actual request.

REJECT deliberately blocks a request. Before adding a rule, check that the target host does not also serve sign-in, verification, or resources required by the page. Guessing its role from the hostname alone can block shared APIs too. If part of a page stops working after the change, temporarily remove the new reject rule and test again. Do not also add proxy exceptions, change DNS, and rewrite URLs at the same time, or you will not know which change restored the feature.

FINAL takes no domain parameter

FINAL is the fallback policy for requests not handled by earlier rules. Common forms include FINAL,DIRECT and FINAL,PROXY; unlike a domain rule, FINAL does not need a match value. Put the fallback at the end of the rule list because it does not wait for a specific domain to match. If it appears earlier, later ordinary rules may never be reached, making new rules seem ineffective no matter how you edit them.

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This snippet means “one exact exception, one suffix range, and DIRECT for everything else.” If your intent is to use the proxy by default, change the final line to FINAL,PROXY and review which earlier DIRECT exceptions should remain. Do not copy only the last line without considering the default direction of the whole file. Changing the default route affects many unlisted requests even when all earlier rules stay the same.

Define your intent before choosing a fallback

Before choosing FINAL, state your goal in one sentence: should only a few specified hosts use the proxy, with everything else connecting directly, or should most requests use the proxy, with a few direct exceptions? The first setup often pairs naturally with FINAL,DIRECT; the second requires careful management of exceptions alongside FINAL,PROXY. There is no single answer for every network. Base your choice on your own access needs and available connection details.

A fallback rule does not automatically switch policies after a failure. FINAL,PROXY does not mean that another policy is tried if an earlier proxy connection fails. It depends on whether earlier match conditions were satisfied, not whether a connection succeeded. Rule matching and connection results happen at different stages. Do not add two policies for the same domain and expect the second to be tried if the first fails; ordinary ordered matching does not work as a retry mechanism.

Keep one clear final route in each rule list to make it easier to read and verify. If the file contains multiple FINAL rules, identify the first one that can be reached, then review any later entries that cannot take effect. Save a copy before deleting anything so you do not remove content that belongs in another section. The finished configuration should make the purpose of each ordinary rule and the route for unlisted requests clear.

06 · ORDER AND SCENARIOS

Rule Order: From Specific to Broad

The first match wins, regardless of which rule looks more specific

For ordinary ordered rules, check from top to bottom; the first match determines the policy. Do not assume DOMAIN always takes precedence over DOMAIN-SUFFIX, or that a new rule near the end automatically overrides an older one. Specificity matters when deciding how to arrange rules, but it does not override their written order. Put precise exceptions before broader rules that might match them first.

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

For api.example.com, the first line already determines the result; the second is not reached. For www.example.com, the first line does not match, so the second handles it. Other unlisted domains reach the final line. You can reason through this before making a connection. If a rule has no chance of being reached on paper, repeatedly switching networks will not help.

Scenario 1: Use the proxy for selected websites only

When only a few websites need the proxy, list the targets using exact domain or suffix rules, then choose FINAL,DIRECT. Avoid starting with many region, keyword, and address-range rules; overlapping scopes can obscure a simple intent. If a site relies on multiple domains, add them gradually based on request records rather than guessing at all its infrastructure from the page name or treating a broad shared string as the service boundary.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This minimal snippet explains the structure; it does not mean that every real website needs only one suffix. When adding rules, note what each new host does, such as serving an API or static assets, and check that the added scope does not change the route for unintended requests. For a full scenario walkthrough, see How to route only selected websites through the proxy, then return here to check the rule order.

Scenario 2: Use the proxy by default, with specific direct exceptions

Another pattern is to put explicit direct-connection conditions first, then use FINAL,PROXY for everything else. Adding a broad DIRECT rule in this setup diverts more traffic from the default proxy route. Before changing anything, identify whether an exception is based on a domain, IP range, or geographic classification. Each calls for a different rule type; a convenient-looking suffix cannot express a condition unrelated to the domain.

[Rule]
DOMAIN,api.example.com,DIRECT
IP-CIDR,192.0.2.10/32,DIRECT,no-resolve
FINAL,PROXY

The two exceptions in this example depend on a hostname and an address, respectively; they are not interchangeable backups. The first depends on domain information being available in the request. The second checks an address and uses no-resolve. During troubleshooting, record which rule matched instead of combining them just because both result in DIRECT. Keeping the match criteria clear helps explain differences when addresses or request patterns change.

Troubleshoot conflicts and maintain rules incrementally

When you find a conflict, start at the expected rule and look upward for anything that could match first, including keyword rules, region rules, and broader address ranges. Do not search only for the exact domain text; a GEOIP rule that does not contain the domain name could still handle the request first. Once you find the cause, move the precise exception or narrow the broad rule instead of duplicating the same entry in multiple places.

After each change, test both a positive and a negative case. The positive case confirms that the target request uses the intended policy; the negative case checks that the scope has not expanded unexpectedly. Testing only the positive case can leave unintended matches unnoticed. Record the mode, configuration name, and steps taken so results from different setups are not compared as if they were the same. There is no need to record sensitive addresses or full authentication details; keep the match criteria and policy result.

Removing redundant rules also calls for checking the order. Two identical lines usually do not need to coexist, but two similar-looking conditions may cover different requests. Note the purpose of each rule, remove them one at a time, and test the main action after each change. Do not combine rule cleanup with a subscription update or server change. Separating changes makes it clear which step to undo if you need to restore the previous behavior.

07 · HOST AND URL REWRITE

Host and URL Rewrite: Not Routing Rules

Host maps names to addresses; it does not select a policy

[Host] maps a hostname to an address. It answers which address a name resolves to; it does not assign that host to PROXY or DIRECT. Requests still follow the active handling mode after the mapping. Resolving a destination name to the specified address does not prove the routing policy is correct, and a correct policy does not mean the mapped address is a valid entry point for the current service.

[Host]
example.com = 192.0.2.10
api.example.com = 192.0.2.11

These addresses are for documentation only. Before entering a mapping, confirm that a service you manage actually requires it and understand how the destination address is maintained. An address returned by a single DNS lookup should not be treated as a permanent entry point. For services using dynamic routing, a fixed mapping may bypass normal selection and cause intermittent failures after a network change or service migration. What looks like an unstable proxy may simply be an outdated mapping.

Mapping a domain to another address does not automatically give the service at that address the right certificate, virtual host configuration, or access permissions. Hostname verification still matters when accessing an encrypted site. If you encounter a hostname or certificate error, check that the service and mapping correspond; do not hide the problem by weakening verification. Host mappings are for targeted configuration of known destinations, not for guessing where an unfamiliar service might be available.

URL Rewrite changes request URLs; it does not replace proxy configuration

[URL Rewrite] defines how matching URLs are rewritten or redirected. Unlike a DOMAIN rule, it matches URL structure, not just the hostname. Before adding one, decide whether you need to change the request URL or only its network route. The latter belongs in policy and routing rules; rewriting a website's URL is not necessary to send traffic through a proxy.

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

This example redirects a plaintext URL for a specified host to its corresponding encrypted URL, using 302 for a temporary redirect. Escaped dots in the regular expression prevent them from matching arbitrary characters in place of domain separators. The start and end anchors limit its scope. The parentheses capture the path, and $1 in the replacement refers to that captured value. When copying the expression, preserve the backslashes and ASCII punctuation; do not let an editor replace them with full-width characters.

Whether a request URL can be observed and processed depends on the protocol and the relevant app features. Writing an HTTPS regular expression in a configuration does not mean the full URL of every encrypted request can be read. Ordinary forwarding does not expose encrypted content. This example does not rely on changing certificate trust. When learning URL rewriting, use test requests you control and whose behavior is clear; do not expand the scope to unfamiliar websites.

Avoid loops, overly broad matches, and exposing authentication details

A rewritten URL may match the same condition again, creating a loop. Compare the input and output side by side, and make sure at least one part—the scheme, hostname, or path—takes the new request outside the original match. Repeated redirects may also come from the destination site's own response; a browser warning alone does not prove that a local rule is looping. Disable the local rewrite temporarily and compare, then check whether the original service still redirects.

A replacement can change where request data is sent, so do not casually rewrite a full URL with query parameters to a different host. Sign-in state, one-time parameters, and in-app redirects may depend on the destination name. Test only with examples that contain no real credentials, and check that the path and query are preserved as intended. A successful regular-expression match proves only that the text condition was met; it does not prove that the workflow still works.

Test Host and URL Rewrite separately. Enable only the mapping first and confirm that the name resolves as expected and access works. Then add one rewrite and check for the intended redirect. If you change both at once, a failure could be caused by the wrong address or the new URL, making it much harder to diagnose. To revert, remove the newly added entry and make a new request so old connections and cached redirects do not affect the result.

08 · VALIDATION AND MAINTENANCE

Validation and Maintenance: Use a Repeatable Checklist

Trace rules from actual requests, not assumptions based on the page

To validate routing, check three things: whether a new request occurred, which condition it matched, and which policy was applied. A page loading is only the final outcome; it does not answer the first two questions. Likewise, a page may fail even after the correct route was selected. Use connection and diagnostic details visible in the app, and record the destination hostname and relevant rule. Do not label every failure a rule failure.

First confirm that the basic network is working, then check Global Routing, the selected configuration, and whether it has been saved and loaded. Generate a new request to the destination, then trace the rule list to find the first matching condition. Only after confirming that the selected policy is expected should you check server connectivity, protocol parameters, and the destination service. This order avoids unnecessary changes and prevents turning a server issue into a long list of permanent direct exceptions.

Connectivity Test and real-world access each prove different things

Interpret Connectivity Test results in light of the test method selected in the app. It provides a useful connection check, but does not cover every domain, path, or protocol used by real-world traffic. After a successful test, still access the actual destination. If the test fails, check whether its target is appropriate for your current setup. Do not use a single result to claim that the entire connection path is healthy, or treat a test value as proof that a rule matched.

Observed behaviorCheck firstNext step
No change after editing a rule.Mode, selected file, and load status.Generate a new request and find its first match.
Main page works, but some features fail.The actual hostname of the failed request.Check dependent hosts and policies.
Policy is correct, but the connection fails.Existing server details and protocol parameters.Troubleshoot the connection path.
Issue started after an update.What was updated and how the configuration differs.Restore a copy and compare one change at a time.

If the server times out, first check that the address, port, authentication fields, and protocol parameters match your existing server details. For TLS, also check conditions such as the hostname and system time; do not try to hide incorrect parameters by changing domain rules. For a step-by-step checklist, see How to troubleshoot server timeouts. Other common connection issues are covered in Connection troubleshooting FAQs.

A minimal reproduction is more effective than stacking exceptions

If a complex configuration is hard to explain, make a copy with one clearly defined target rule and a FINAL rule. Temporarily remove unrelated mappings and rewrites, then test the same action. If the minimal configuration behaves as expected, restore the original rules in groups until you find which group changes the result. This temporary simplification is only for troubleshooting; do not replace your long-term configuration without reviewing it. After restoring the rules, retest other features that depend on them.

Keep the network, server selection, and test action as consistent as possible. Switching networks changes DNS and connection conditions; switching servers changes the proxy path; updating a subscription may change entry parameters. If several of these change at once, you cannot tell which one caused the result. If you need to compare networks, record the conditions before and after the switch, and do not combine it with a rule change in the same test.

Updates, Rollback, and Safe Sharing

Keep a working baseline for configuration maintenance. Before a major change, make a copy and note its purpose, affected sections, and expected behavior. Afterward, retest the same key actions. For subscription update instructions, see Importing and updating subscriptions. If behavior changes after an update, compare the contents first to see whether server details or the rule file changed, then decide which one to restore.

When describing an issue to someone else, share only the minimum necessary snippet, mode, and match result. Remove full subscription URLs, authentication fields, real server details, and records that could expose personal browsing activity. Configuration files may contain other sensitive settings as well as rules; do not share the entire file just because one section appears to contain only domain names. Check diagnostic records for personal information before sharing them too.

After restoring the original file, confirm that it is selected; changing a copy's name back to the original does not complete a rollback. Reload the file, make a new request, and check the expected domain, a negative case, and the fallback. If only an existing connection is behaving strangely, end it and test again. If a new request still fails, continue checking mode, rules, policy, and the connection path in order. Do not keep rewriting the same rule in different syntax.

Get Shadowrocket on the App Store