Official Manual · Configuration Reference

Shadowrocket
Configuration Fields andRules Reference

First confirm which configuration is active, then check rule conditions, order, and final policy. Organized by file structure, this reference is designed for reviewing an existing configuration.

New to Shadowrocket? Start with the getting started guide to import your existing subscription and connect for the first time. This reference explains how configurations work without repeating the initial setup steps. To get the app, visit the downloads for all platforms.

[General] [Rule] [Host] [URL Rewrite]

01 · Configuration File Structure and Scope

Shadowrocket configuration files use square brackets to mark sections, each responsible for a different set of options. When reading a file, start with the section name, then check the syntax within it. Not every comma-separated line is a rule. Common sections include [General] for basic behavior, [Rule] for routing requests, [Host] for domain-to-address mappings, and [URL Rewrite] for rewriting matching URLs. Section boundaries matter: a line placed in the wrong section may not work as intended, even if its syntax is otherwise correct.

Start with a Minimal File

This snippet illustrates the structure; it is not a complete configuration for every network. It keeps a basic system-related setting, followed by a domain condition and a fallback rule. example.com is a documentation example domain; replace it with a target you need to test and are authorized to use. The PROXY rule requires an available proxy selection in the app. Copying this text alone does not provide server settings, authentication details, or a subscription.

[General]
bypass-system = true
dns-server = system

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

Configuration files, server lists, and connection status are separate layers. The server list stores connection details; the configuration describes how traffic is handled; and the connection switch determines whether system traffic enters the current processing flow. A file appearing in the list does not mean it is selected, and selecting a file does not guarantee that current traffic follows its rules. Also check the current Global Routing mode, especially if you temporarily switched to Proxy or Direct and forgot to switch back.

Opening, Editing, and Switching Are Different Actions

In Config, first confirm which file is active, then open its editing or details view. The location of these controls may vary by platform; follow the labels shown in your app. Keep a copy of the original before editing. After saving, check for parsing errors and confirm the selected file. When troubleshooting, use one clearly identified test copy at a time. Mixing files with the same name, remote files, and local copies can lead you to edit a file that is not actually in use.

SectionPurposeWhat to Check
[General]Basic behavior and parsing settingsField names, values, and applicable conditions
[Rule]Select a policy based on request conditionsCondition scope, order, and fallback policy
[Host]Fixed domain-to-address mappingsAddress validity and resolution scope
[URL Rewrite]Match and rewrite URLsExpressions, target URLs, and visible request scope

Blank lines mainly make a file easier to read; they do not turn adjacent rules into separate workflows. Section headings, however, change how subsequent lines are interpreted. When merging files by hand, common mistakes include copying rules without their section heading or appending the basic settings from one file to the end of another file's rules. A safer approach is to merge and compare one section at a time, rather than concatenating two complete files. Do not guess how duplicate fields are handled: remove ambiguity and check the result after saving.

When copying configuration text from a webpage or chat, watch for full-width commas, curly quotation marks, invisible spaces, and long lines broken by automatic wrapping. Rule fields use English commas, while key-value fields generally use an equals sign. A line that only appears wrapped in the interface may not contain a line break, but pasting can insert one. If a rule has been split into incomplete lines, check it in a plain-text editor rather than adding more rules to work around a syntax problem.

You can change the order in which you consult this reference based on the problem. If a file will not save, check its structure and syntax. If traffic uses the wrong policy, check the mode and rule order. If a domain will not resolve, check basic settings and address mappings. If only a specific URL redirects incorrectly, check URL Rewrite. This separates whether the file can be read, whether a rule matches, and whether a connection succeeds—so an unavailable server is not mistaken for a rule syntax error.

02 · General, DNS, and Basic Behavior

The [General] section configures basic behavior; it does not select a proxy for each domain. For each field, ask which requests it affects, whether it changes name resolution, and whether it relates to system services. A configuration with more fields is not necessarily more complete. Unfamiliar values make troubleshooting harder. A file with only necessary settings, each of which you can explain, is usually easier to verify and maintain.

Understanding Two Example Fields

bypass-system = true enables bypass behavior for system-related traffic. This does not mean you can omit all direct rules, nor does it turn off the system proxy. Check the current app settings and runtime environment to determine which system traffic is affected. dns-server = system uses the system DNS resolver; it does not guarantee fixed results or identical answers across networks.

[General]
bypass-system = true
dns-server = system

DNS resolution and routing are related, but they are not the same thing. Domain conditions can match a domain carried in a request or identified by the client; address conditions require a destination address to compare. Some requests start with a domain, others connect directly to an address, and some connections reuse earlier results from a cache. So entering a domain in a browser does not mean that every step will trigger a new lookup, nor does it prove that the request used a particular DNS server.

Distinguish Resolution Failures from Connection Failures

When a destination will not open, first identify where the failure occurs. If the domain does not resolve to a usable address, check the current network's resolution, system DNS, and fixed mappings. If an address is available but the connection fails, check the policy, proxy server, and destination service. Changing the final policy from direct to proxy will not necessarily fix an incorrect fixed address. Likewise, a successful DNS lookup only confirms that resolution returned a result; it does not mean that the address is reachable through the current network.

Switching between Wi-Fi and mobile data can change the system's DNS resolver, local network addresses, and what is reachable. An internal company hostname may resolve only on a particular network; a home device may use an address assigned by the router; and a public site may return different service addresses depending on network location. For troubleshooting, keep the network fixed and test one specific target. If you switch networks, replace DNS settings, update a subscription, and edit rules all at once, you will not know which change restored access.

Do not mechanically combine DNS settings from multiple configurations. Different fields may control the resolver, fallback conditions, or behavior in specific cases. Although they may all look like ways to “add an address,” they can change request order and failure handling. The basic snippets here are intended to make tests reproducible. Before adjusting more specific behavior, check the field descriptions in your current app and compare results for one target at a time. If there is no specific problem to solve, there is no need to change resolution settings just to add more fields.

Caching and Repeat Testing

After changing resolution settings, existing connections and caches may affect observations for a while. End the relevant requests, reconnect the client if necessary, and try again with a new request. If the app provides controls for logs or caches, use the options available in its current interface. A page that still shows old content after a refresh does not prove that a rule failed to save: browser content caches, persistent app connections, and DNS caches are separate layers, and clearing one may not affect the others.

When recording basic settings, note the current network, whether the system uses additional network configuration, and whether the test target is a domain or a direct address. On a managed device or workplace network, do not remove organization-required settings just to test a rule. Establish a reproducible baseline, then isolate one variable at a time. If the same file behaves differently on two networks, that often points to changed environmental conditions, not a change in the file itself.

Keep a field only if you can explain its purpose, verify it in the current environment, and restore the previous state if needed. After fixing the issue, remove temporary unfamiliar values and keep the original copy with a brief change note. If the problem affects one target, continue with the domain and address conditions below. If all targets fail, also check the connection mode and the status of your existing servers rather than adding the same conditions repeatedly to the rules section.

03 · Global Routing and the Three Policies

Global Routing sets the overall routing mode; the policy at the end of a rule determines what happens when that rule matches. These are similar-sounding terms at different levels. The interface options Config, Proxy, and Direct set the overall mode. In configuration text, PROXY, DIRECT, and REJECT are rule policies. To determine whether a configuration is working as intended, check both levels—not just one.

Check the Mode Before Analyzing Rules

For everyday rule-based routing, use Config and confirm which configuration file is selected. In Proxy mode, traffic follows the proxy mode; you cannot use its behavior to verify whether a rule sends a domain direct. In Direct mode, a successful connection does not prove that the proxy server works. These modes describe the overall routing intent. System bypass behavior and request visibility may still affect individual requests, so do not treat a mode label as a guarantee that it covers all system traffic.

ModePurposeWhat to Check
ConfigRoute traffic according to the current file's rulesCheck the file, rule order, and first matching rule
ProxyTemporarily test the proxy routeDoes not prove that a direct rule is working
DirectTemporarily test the direct routeSuccess does not prove that the proxy server is available

What the Three Rule Policies Do

PROXY sends the request to the current proxy selection; it does not mean the configuration automatically specifies a server that is always available. The rule can match and still fail if the server is down, authentication is incorrect, or protocol settings are wrong. DIRECT connects through the current network without a proxy and still depends on local DNS, routing, and the destination service. REJECT blocks matching traffic. It is not a way to select a faster route and should not be used as a generic fix for unexplained errors.

[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,local.example.com,DIRECT
DOMAIN,service.example.com,PROXY
FINAL,DIRECT

The reject rule above matches only the example host; the direct and proxy rules each target a specific host as well. The file does not measure speed, and a failed proxy connection will not automatically make the request go direct. If you need fallback behavior, first check whether the current app supports it and configure it explicitly. Listing multiple policy names does not create automatic failover. A rule line's final field normally specifies the action to take when its condition matches.

Distinguish a connectivity test from a real request. A result from Connectivity Test only applies to that test's conditions; it does not replace a request to the target site. The target may require a different port, transport capability, or several related domains. Troubleshoot in three stages: verify that your existing server is basically usable, confirm the specific target matches the expected policy, and then check whether the full application workflow succeeds. Do not treat these checks as interchangeable.

Restore Config Mode After Temporary Tests

If switching temporarily to proxy mode restores access, the proxy route is worth investigating, but that does not yet identify a faulty rule. Return to config mode and check which rule the failed request originally matched. If it went direct, determine whether an exact rule is missing, a broader condition matched first, or the domain was not identified. Do not leave the app in a temporary mode for one target while assuming other apps still follow exceptions in the configuration.

Success in direct mode and failure in proxy mode does not prove that every rule should be changed to direct. The current proxy server may be unavailable, the destination may not accept that route, or the server settings may not match your existing details. Keep the target and network unchanged, change one variable at a time, and record the mode and result for each test. For more on the three modes, see Global Routing: Understanding the Three Modes.

When maintaining a configuration, make sure you can explain the purpose of each policy: why a host needs a proxy, a subnet needs direct access, or a target needs to be blocked. Broad REJECT rules without a clear purpose need particular care because they may affect sign-in, updates, or resource loading. Check essential everyday tasks, not just whether the main page loads, before keeping or reverting a policy change.

04 · DOMAIN Rules

Domain rules are useful for specifying which route a host should use and are usually easier to understand than a handful of manually collected IP addresses. Three common conditions are DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD. They match an exact hostname, a domain and its subdomains, or a string contained in a domain name, respectively. Define the scope you need first, then choose the narrowest condition that works. A short rule is not automatically a reason to use a keyword match.

Exact Hostname and Domain Suffix Matching

DOMAIN matches only the hostname specified. An exact rule for api.example.com does not also cover example.com or the service's image host. DOMAIN-SUFFIX covers the domain itself and its subdomains, such as example.com and api.example.com. Suffix matching follows domain boundaries; it is not an arbitrary string-ending match. A similar-looking hostname outside that domain is not part of the same scope.

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

This set of rules sends the API host through a proxy first, then routes other hosts in the same domain directly. The example shows an exact exception before a broader suffix condition; rules are not automatically sorted by specificity. If you swap the lines, the suffix condition matches the API host first, leaving the exception no chance to apply. Follow the actual line order when reading a file—do not mentally move more specific rules to the top.

Keep Keyword Matches in Scope

DOMAIN-KEYWORD checks whether a domain name contains a given string; it does not express domain ownership. The keyword example matches a broader range than the suffix example.com and may match multiple unrelated domains. Use it only when you have confirmed that broad matching is needed, not as a long-term substitute for an unknown hostname. Short keywords increase the likelihood of false matches and make troubleshooting harder.

RuleWhat It MatchesCommon Boundary
DOMAIN,api.example.com,PROXYThe specified API hostnameDoes not automatically include other hosts in the same domain
DOMAIN-SUFFIX,example.com,DIRECTThe domain and its subdomainsDoes not match any arbitrary similar string
DOMAIN-KEYWORD,example,PROXYA string contained in the domain nameMay include unrelated domains

Enter a hostname in a domain condition, not a full URL. The scheme, port, path, and query parameters are not part of the domain name. Pasting a complete URL into a suffix field usually means you are matching the wrong kind of value. Standard domain conditions cannot distinguish URL paths. The sign-in page and images on the same host may match the same domain rule. To handle URL-specific behavior, first understand the URL Rewrite limits below; do not append a slash to a domain.

One Page Can Use Multiple Domains

A working main page and a failed sign-in do not necessarily mean the main domain rule is wrong. The page may also request an authentication API, static resources, or other service domains. Start with the actual failed request, identify its hostname, and then decide whether it needs a separate rule. Do not route every domain containing the same brand name identically just to make a workflow work. Similar names do not prove that requests serve the same purpose or need the same route.

For multi-step workflows such as sign-in and payments, check the entry point, redirects, callbacks, and required resources in the same test—not just the home page. If an API needs a proxy while the main page goes direct, keep that precise distinction and observe the result. Cross-domain failures can also come from server permissions, account status, or app cache. Rules control the connection route; they cannot fix incorrect credentials or change the destination service's own restrictions.

Evaluate duplicate domain rules by the position of the first match. If two identical conditions point to different policies, the later one is not a fallback. If one suffix includes another, account for the overlap. When cleaning up a file, look for duplicate hostnames first, then parent and child domains, and finally overlaps between keywords and other conditions. Save a copy before removing duplicates, and confirm that the retained rule is in the right position; do not deduplicate by text alone.

If a domain rule appears to have no effect, first confirm that the target opened a new connection to that hostname, then check whether the request log shows a recognizable domain. Direct access by IP address, reuse of an existing connection, or a different redirect path can make the actual request differ from what you expected. Check the rule order only after confirming that the request and condition correspond. This avoids repeatedly adding equivalent rules for the wrong host while leaving the real request untouched.

05 · IP-CIDR, GEOIP, and USER-AGENT

Address rules match destination IPs, not website names. IP-CIDR represents an IPv4 address range, IP-CIDR6 an IPv6 range, and GEOIP classifies addresses using location data. These conditions can coexist with domain rules, but they use different matching criteria. Choose a condition based on the information available for the request. A domain suffix or page language alone does not tell you whether an address will match a particular GEOIP condition.

A CIDR Block Represents a Set of Addresses

192.168.0.0/16 represents a private address range; it does not mean “every local network currently connected to this device.” Home networks may use other private ranges, and workplace networks may use different addressing plans. Before writing a rule for a local service, check its actual address and network range rather than assuming that a range found online applies to your environment. A rule does not create a network route: even with a direct policy, a device cannot connect if the network is unreachable.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR6,fc00::/7,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

The example includes a private IPv4 range, an IPv6 link-local range, and an address classification condition. It does not mean everyone should enable them as written. A longer prefix generally represents a smaller range; /32 represents a single IPv4 address and /128 a single IPv6 address. When editing, make sure the address and prefix belong to the same address family. Do not put an IPv6 address in an IPv4 rule or mistake a port number for a prefix length.

Resolution Options Are Not Performance Switches

Address rules may need to resolve a domain before comparing its IP. A rule that supports the no-resolve option can use it to avoid triggering resolution solely for that match. It does not disable DNS for the whole device. If a request already has an address, it may still match the address condition. If the request has only a domain and no address is available, the rule with this option may not match, and evaluation continues. Add it only when that behavior is what you want.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

GEOIP,CN,DIRECT classifies an address by location data; it does not match text in a domain name, nor does it mean that every related website uses only that address category. Content delivery, service migrations, and data updates can all produce results that differ from expectations. If a particular service must consistently use a specific policy, identify its actual domain and consider an explicit rule rather than relying only on a broad classification. Classification data is one matching criterion, not proof of a service's location or ownership.

What USER-AGENT Can Match

USER-AGENT matches the corresponding identifier in a request; it is not the same as routing by operating-system app process. Multiple apps can use the same identifier, and one app may use different values for different request types. More importantly, ordinary encrypted connections do not automatically expose their request fields. Do not assume that entering an app's name will identify all of its traffic. Before using this condition, confirm that the current request actually provides a value it can match.

[Rule]
USER-AGENT,ExampleClient*,PROXY
FINAL,DIRECT

The identifier here is a pattern example showing wildcard matching; it is not the fixed identifier of a real app. When testing, check the actual value in a request you are authorized to inspect, including its capitalization, spaces, and wildcard scope. A browser's display name is not necessarily the full request field. Avoid piling up guessed app names as rules. If you cannot confirm that the field is visible, use a verified domain condition instead of treating a missed match as a proxy server failure.

There is no inherent global priority among address, domain, and request-field conditions; they still follow the order in the rules section. A broad address condition near the top may match before a later domain exception. An overly broad request identifier may also change results that were intended to depend on domains. Review condition types and line order together, and test the exceptions you need to preserve. Checking each rule's syntax in isolation is not enough.

If the same domain gets different policies in different tests, check whether the requests used IPv4 and IPv6 addresses separately, matched different subnets, or received different resolution results. Do not immediately disable one address family as a fix. Confirm the address actually used by the target, then compare whether existing rules express the same intent for both address families. If your environment has a real limitation, document it and how to revert the change, then retest when the network changes.

06 · Match Order, Exceptions, and FINAL

The key to reading [Rule] is to scan from top to bottom and use the policy from the first matching condition. Rules are not a voting system, and their results are not combined. Exact rules do not automatically take precedence over suffix rules, and domain rules do not automatically take precedence over address rules. Priority comes first from line order. This explains why two files with the same rules can behave differently when those rules are arranged differently.

Put Specific Exceptions Before Broader Rules

A common layout puts explicit exceptions first, general groups in the middle, and a fallback at the end. For example, if one API host needs a proxy while other hosts in the same domain should connect directly, put the exact API condition before the parent-domain suffix. “Exceptions first” is an organizational guideline, not a mandatory category order. If an address range needs priority for a specific reason, first identify which domain requests it will override, then order the rules accordingly. Do not copy an order without understanding its purpose.

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

For the API hostname, the first line matches and selects the proxy; the parent-domain condition does not change the result. For another host in the same domain, the first line does not match, so the suffix condition selects direct. A target outside these domains and the listed address range continues down the rules. When tracing a request line by line, mark each condition as “matches,” “does not match,” or “not enough information to determine a match.” Do not skip to a conclusion based on intuition.

FINAL Is a Fallback, Not an Automatic Fix

FINAL sets the policy used when none of the preceding conditions match. It takes no domain argument; examples include FINAL,PROXY and FINAL,DIRECT. It usually belongs at the end of the rules section so earlier conditions can be evaluated. If the fallback comes first, later rules no longer serve their purpose in the normal sequential matching process. Do not use multiple fallbacks to imply backup behavior. One clearly defined final choice is easier to understand.

Broad keywords, address classifications, and parent-domain suffixes can all preempt later exceptions. If a rule never seems to take effect, inspect all earlier conditions that could cover it, not just rules with identical text. Exact duplicates are easy to spot; overlapping scopes are less obvious. List the affected target and simulate evaluation from the first line to find the earliest match. Then decide which rule to move instead of copying it into several sections.

Verify the Intended Change with a Test Matrix

Before changing rule order, choose a specific test target for each category: an exact exception hostname, another host in the parent domain, a local network address, and a target that should fall through to the fallback. Write down the expected policy for each, then check the actual logs after editing. Testing only the problem hostname can fix the exception while breaking other requests in the parent domain. A small set of tests is enough if it covers the rule boundaries. For every broad condition you add, include at least one target that could be matched by mistake.

Test TargetExpected First MatchExpected Policy
api.example.comExact domain exceptionPROXY
www.example.comParent-domain suffix conditionDIRECT
192.168.1.20Private IP rangeDIRECT
Target that matches no earlier conditionFINALPROXY

When combining configurations from different sources, check the original fallback and exceptions in each file. Two files that work separately may not work after merging if they use opposite default policies. Choose one final policy, move the necessary exceptions into a single rule chain, and check for overlaps. Do not keep two complete rule sequences and expect the app to reconcile their authors' different intentions.

Remove temporary priority rules when testing is done. Moving a target to the top can help confirm its route, but leaving it there may preempt exceptions added later. Put the final rule in a position you can explain and record why it changed. For cases where a rule matches correctly but the connection still fails, continue to the verification steps in the final section or read the rules and troubleshooting FAQ. Do not keep changing rule order to address a problem unrelated to order.

07 · Host and URL Rewrite: What They Do

[Host] and [URL Rewrite] can both affect the final result, but they do different things. The first maps a domain to a fixed address; the second rewrites URLs that match a condition. Neither is the same as choosing a policy in [Rule]. Troubleshoot by asking separately: which hostname is requested, which address it resolves to, whether the URL changes, and which policy handles the connection. Mixing these questions up can lead to confusing resolution, redirects, and routing with one another.

Use Fixed Host Mappings for Known, Maintained Addresses

The example maps a documentation hostname to a documentation address to show the format; it is not a real service address. The domain is on the left of the equals sign, and the address is on the right—not a proxy policy. Once set, the mapping can supply the address used for resolution, but whether the connection uses a proxy still depends on the applicable rule and current mode. A fixed mapping and a proxy rule for the same domain are not contradictory; they describe different layers of behavior.

[Host]
lab.example.com = 192.0.2.10

Fixed mappings are suited to test or internal services with a clear owner. Avoid applying them casually to public sites that rely on dynamic routing. After a service migration, address change, or content delivery update, an old address may stop working or point to an unsuitable service. The fact that a configuration saves does not prove that its address is still correct. Record why the mapping exists and how to verify it. Once normal resolution works again, decide whether the override is still needed so a temporary workaround does not become a long-term problem.

A fixed address does not rewrite the domain in an encrypted site's certificate or bypass certificate validation. If the address does not serve the requested hostname, the connection may succeed but show the wrong page, fail certificate validation, or be rejected. Do not ignore security warnings to “prove” a mapping works; check the address and service configuration instead. Accessing a site by domain and entering its IP address directly are not equivalent tests, as the latter may change the host information received by the destination.

URL Rewrite Applies to Matching URLs

A rewrite rule generally includes a matching expression, replacement target, and action. The example redirects an unencrypted URL on a documentation host to an encrypted URL on the same host while preserving the path. The dots in the expression are escaped with backslashes, so they match literal dots in the domain rather than any character. The leading anchor limits matching to the start of the URL. This snippet illustrates the syntax and scope; it does not mean that every target should use this redirect.

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

Here, 302 is the redirect action, and $1 refers to the content captured by the earlier parentheses. When editing the expression, check both its match scope and replacement result. In particular, check for duplicate slashes, missing paths, and query parameters that may not be preserved as intended. Start with a simple test path that contains no personal information, then test any parameters required by the real workflow. Do not paste a complete request containing authentication details into a public issue.

Check Encrypted Requests and Redirect Loops Separately

On ordinary encrypted connections, the full URL path is not automatically visible to the client, so the presence of a rewrite section does not mean every encrypted request can be inspected and rewritten. This reference does not require enabling decryption for rule-based routing; most needs for domain-based policies do not require URL rewriting either. If you want a site to use a proxy, consider a domain rule directly rather than trying to redirect every URL on that site.

A redirect loop can occur when the destination URL still matches the original expression or two rules keep redirecting to each other. During testing, check whether the final URL keeps changing and compare results by disabling the most recently added rewrite rules one at a time. The destination service may also redirect, so not every loop comes from a local rule. Keep the rewrite condition as small as possible and compare behavior with that section disabled to determine whether the loop starts locally or in the destination's response.

Before merging configurations that include URL Rewrite, check the purpose, target domain, and scope of each rule—not just whether the file saves. An overly broad expression may affect unrelated paths, and a fixed mapping may send multiple features to the wrong address. If a rule has no clear purpose, keep the original file and leave that section disabled for now. For routing problems, start with routing rules. Add fixed resolution or URL rewriting only when needed, with a separate test and rollback plan for each change.

08 · Verification, Troubleshooting, and Maintenance

The final test of a configuration is to compare the expected behavior with the observed result, not merely to check whether the file saves. A successful save mainly means the text passed the current parsing checks. A request matching the expected rule means the routing decision worked as designed. A successful task means the current network, server, destination service, and business requirements all worked together in that test. These conclusions have different scopes; record them separately rather than reporting that everything is working based on one partial success.

Follow a Minimal, Reversible Test Process

Before you begin, keep a copy of the active file and note the selected configuration, Global Routing mode, network environment, and current server selection. Then change just one type of condition—for example, move a rule for one target domain without changing the resolver at the same time. Save, confirm the change is active, and make a new request to the target. Check the connection or request logs available in the app for the hostname, destination address, matched rule, and policy. Log locations may vary by platform; use the options shown in your app.

If the actual policy differs from what you expected, first check the mode and selected file, then trace overlapping rules from top to bottom. If the policy is correct but the connection fails, check the server settings, destination service, and current network. If only part of a page or workflow fails, identify the hostname used by the failed request instead of rewriting the entire configuration. This approach limits unrelated changes and keeps recovery simple: undoing this round of edits should restore the known state from before testing.

Observed IssueCheck FirstDo Not Assume
File will not saveSection names, commas, field count, and line breaksThat the server is already down
Request uses an unexpected policyActive file, routing mode, and first matching conditionThat the destination site must be down
Policy is correct but the connection failsServer settings, resolution, and destination reachabilityThat adding the same rule again will fix it
Home page works but sign-in failsAuthentication API, redirects, and related domainsThat the parent-domain rule covers every part of the workflow

Do not troubleshoot server or subscription issues by changing rules

If an existing server times out, check the address, port, authentication details, protocol-specific fields, and system time one by one, confirming they match your own information. Do not change every failure to direct, and do not assume that repeatedly updating a subscription will change local rule order. A subscription update mainly changes the data it provides; a configuration file may come from another source. Whether the two are linked depends on how you use them. For details, see How to Troubleshoot Server Timeouts and Connection Failures.

When managing multiple existing subscriptions, distinguish subscription groups, manually added entries, and configuration files before deleting anything. Duplicate entries after an update do not mean you need to copy more rules. Do not put a full address containing access credentials in a configuration note just to identify an entry. See Organizing Multiple Subscriptions and Duplicate Entries to sort out the sources before investigating how connections and rules relate.

Keep Remote Updates Separate from Local Edits

A remote configuration update may replace local edits, depending on the file source and update method. If you need to keep custom rules, first confirm whether the active file is an independent local copy or is still maintained by remote content. Back it up before updating. Afterward, compare basic fields, exception rules, and the final policy—not just the filename. Avoid maintaining multiple files with the same unclear name. A name can describe a file's purpose, but it cannot confirm that the file is active.

When sharing troubleshooting details, include only the rule snippet needed and a sanitized description of what happened. Server addresses, subscription URLs, passwords, authentication fields, and private destinations may be sensitive; remove them before sharing. Replace real hosts with documentation example domains while keeping the rule types and order intact so others can still discuss overlaps. Check screenshots for sensitive details in notifications, lists, and logs too. A partial screenshot is not automatically free of credentials.

When using Shadowrocket across devices, verify each platform's network environment and available settings separately; results on one device do not automatically apply to all platforms. Shadowrocket is available for iPhone, iPad, Mac, Windows, Android, and Linux. The iPhone and iPad versions cost $2.99 as a one-time App Store purchase. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. For downloads and first-time installation, see the installation guide on the downloads page. For iPhone and iPad, see the App Store listing for system requirements.

Before wrapping up, restore your everyday routing mode, remove temporary test rules, keep the final file with a brief change log, and rerun the boundary tests you planned. If another issue comes up, first compare what changed in the network, server, or configuration instead of discarding all your settings. For the initial import and connection steps, return to the getting started guide. For unclear field names, check the glossary; for common usage questions, see the FAQ. Keep setup, field reference, and troubleshooting focused on their respective tasks.