01 Settings baseline
Initial values and Global Routing
Distinguish initial, inherited, and current values
When you open Shadowrocket, note the connection status shown in Home, the selected server, and the current Global Routing mode. Then check Config to see which configuration is actually enabled. Seeing a file in the list only means it’s saved; it doesn’t mean the connection is using it. Likewise, a server appearing in the SERVER list doesn’t mean every rule routes traffic through it. Recording these details separately is more useful for troubleshooting than simply noting “connected.”
In this guide, “initial value” means the state shown before you make changes, or the behavior determined by the system and active configuration when a field is unset. It isn’t a fixed set of values shared by every device. Subscription updates, switching files, and restoring from an older device can all carry existing settings into the current setup. If the interface doesn’t show a default explicitly, leave the field blank or keep its existing state rather than entering a specific number to match an example. When comparing settings, first note whether the original value was blank: manually entering what looks like the same value isn’t always equivalent to inheriting the default behavior.
Choosing between the three modes
| Mode in the interface | When to use it | What it doesn’t tell you |
|---|---|---|
Config (configuration) | Use the verified active configuration for everyday rule-based routing. | The server list alone can’t show where an individual request is routed. |
Proxy (proxy) | Use briefly to check whether the current proxy can reach the same target. | A successful test doesn’t prove the original routing rules are wrong. |
Direct (direct connection) | Use briefly to check whether the target is reachable directly over the current network. | This does not turn off the system VPN connection. |
For everyday rule-based routing, use Config and make sure you already have a working configuration. If one site fails, first reproduce the issue in the current mode. Then keep the network, server, and target the same, switch modes, and test again. If Proxy works but Config doesn’t, check which rule matches and where its policy points. If neither works, check whether the proxy path is available before changing rules. If Direct also fails, investigate the target service, network connection, or DNS results. Restore the original mode after testing so a temporary switch doesn’t affect later access.
Minimal rule example and rollback
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
This snippet illustrates rule order; it isn’t a complete configuration. The first rule sends requests matching example.com and its subdomains to PROXY. The second sends requests that don’t match earlier rules to DIRECT. Rules are checked from top to bottom. Put narrower rules before broader rules that could override them, and use FINAL as a fallback. A webpage may also request images, sign-in resources, or APIs from other domains. A match for the main domain doesn’t mean the entire page uses this one rule; troubleshoot the request that actually failed.
Before editing, keep a recoverable copy of the configuration, then change just one rule in a duplicate. After saving, confirm the duplicate is enabled. Test one target that should match the rule and another that shouldn’t. If both behave differently, check whether the wrong file is active or a broad rule was moved too high in the list. Remote configurations may replace file contents when updated, so keep long-term local changes in a separate copy rather than relying on memory to recreate them. For other configuration sections, see A guide to .conf file sections.
To confirm a change worked, reproduce the same issue once before the change and verify it’s gone afterward. If you switch modes and networks at the same time, you can’t tell whether routing changed the result or the original network recovered. If needed, restore the original value and check whether the same issue returns. If the problem can’t be reproduced consistently, preserve the details of what happened rather than treating one successful attempt as the new default.
02 DNS resolution
DNS: resolvers, overrides, and fallback
Check what’s resolving the domain before choosing an address
DNS translates domain names into addresses needed for a connection. A successful lookup only means an address was returned; it doesn’t prove the address is reachable or that traffic follows the intended policy. Conversely, a working server paired with a DNS timeout for a particular domain can make a site appear unavailable. In that situation, compare a known-working site with the failed target on the same network, then check whether the failure occurs during resolution, connection, or the application response.
First check [General] and [Host] in the active configuration. The former may specify DNS settings; the latter may define local mappings for specific domains. If only one domain has a problem and it has a mapping, check whether that mapping is still valid first. Changing DNS may not affect a result determined by a mapping. If no override is visible, keep the system or configuration’s current resolver as your baseline. A blank field doesn’t stop resolution, and it doesn’t prove that a particular public resolver is in use.
System, custom, and encrypted DNS
System DNS is a good choice when the network already provides a working resolver, and is the preferred baseline when troubleshooting. Company and campus networks may only resolve internal names through their own DNS. Sending all requests to an external resolver to fix one public domain can also break access to internal sites. On Wi-Fi networks with a sign-in page, complete the system’s network authentication first, then decide whether DNS needs changing. Resolution and connectivity can differ before and after authentication, so one test can’t stand in for the other.
If you need a custom resolver, use a service whose purpose you understand and that’s reachable from your current network. Encrypted DNS, such as DoH or DoT, protects queries in transit to the resolver; it doesn’t route all app traffic through a proxy or make every returned address reachable. If the resolver itself is specified by a domain name, that name must also be resolved and the service reached. Don’t change the resolver address, encryption method, and routing rules all at once. If something fails, changing all three makes it hard to identify what caused the timeout.
Choose a troubleshooting path based on the scope of the failure
If only one app fails, use another app on the same device to access the same target and see whether the difference could be due to the app’s cache or DNS behavior. A browser may use its own encrypted DNS or reuse an existing connection, so success in another app alone doesn’t prove system DNS is working. Start a fresh request before testing and note the domain and time. Don’t treat cached content on an old page as proof that the site is currently reachable.
If a domain fails on Wi-Fi but works on cellular, keep the configuration unchanged and switch only the network to compare. If the target returns an address but won’t connect, check the route to that address rather than concluding that DNS is at fault. A target may have both IPv4 and IPv6 addresses. If one path has a problem, apps may behave differently depending on their address-family preference and connection fallback. Note the address type and error you can actually observe; don’t treat disabling an address family as a standard setting for every device.
If a widespread failure started after changing DNS, restore the previous resolver settings first. Keep the same mode and network, then retest one public domain and one internal name that previously worked. Removing a temporary override is not the same as replacing it with a different address; rollback should restore the original inherited state. A brief recovery after switching networks doesn’t prove the problem is fixed; a new connection may simply have been established. Wait for a similar request to occur again and confirm the issue isn’t being masked by an old cached result or reused connection.
Finally, note whether the change was made in the configuration file or as a device-level setting. The former may disappear when the file is replaced; the latter may not carry over when the file is copied to another device. If the same problem returns after a subscription update, check the active file’s DNS settings first rather than starting over by selecting a server.
03 Connection triggers
On Demand: triggers and persistent connections
On Demand controls when a connection starts, not where traffic goes
On Demand lets the system decide whether to start a VPN connection based on available conditions. It’s separate from Global Routing: the former controls when to connect, while the latter affects how traffic is handled after the connection is established. Setting a network as a trigger won’t automatically route a domain through PROXY; adding a proxy rule won’t replace the system’s On Demand conditions. Before troubleshooting, identify whether the issue is “doesn’t start” or “the target is inaccessible after connecting.”
For your first setup, keep connection control manual: start the connection from Home, confirm that ordinary targets and those requiring a specific policy behave as expected, then check On Demand in Settings. A device restored from system settings or copied from another device may already have trigger conditions, so don’t assume the feature is off just because the setup looks new. Check the current toggle and the system VPN status. If the connection comes back after you disconnect manually, check whether a condition is still being met instead of repeatedly turning off the main switch.
Start with one clearly testable scenario
First choose a specific goal, such as connecting automatically only on one type of network. If the interface offers a matching condition, start with that single condition and leave the others unchanged. Note one scenario where it should trigger and one where it shouldn’t, then test each by switching networks. Whenever you join a new network, first confirm that the system has finished connecting, then check whether the VPN starts. A delay of a few seconds while the system is still obtaining an address doesn’t by itself mean the trigger failed.
If a condition depends on a Wi-Fi network name, check the name of the network currently connected to the device rather than guessing based on the router’s location or a nickname. Different access points may use the same name, so a network name is only a matching condition, not proof that the network is trusted. If a location has multiple ways to connect, confirm which network the device actually ended up using during the test. Otherwise, a fallback to cellular could be mistaken for a matching Wi-Fi condition.
Test an exclusion condition separately as well. If the VPN is already connected, seeing it stay connected after joining a network doesn’t prove that it will start automatically there. When possible, begin from a known disconnected state in a controlled environment to distinguish an existing connection from a new one started by the system. If the rules list supports multiple conditions, add them one at a time and rerun both scenarios after each addition. This helps reveal overlaps instead of leaving you with a set of conditions you can’t easily untangle.
Automatic reconnection, public networks, and battery use
On public Wi-Fi, the system may need to open a sign-in page before you can get online. Automatic connection can make “not authenticated yet” and “proxy connection failed” happen at the same time. To isolate the issue, temporarily disable On Demand triggers and disconnect manually, complete network authentication, then connect manually. Once access works, restore the original conditions and test them again. Re-enable the original setting afterward, and don’t permanently remove other valid conditions just for one temporary network.
Whether to keep a persistent connection or use On Demand depends on how often you switch networks and how you use your device. On Demand doesn’t guarantee lower battery use: frequent reconnects caused by trigger conditions can add overhead. For a fair comparison, keep the configuration and main usage scenarios the same. Compare system battery usage and reconnect counts over similar observation periods rather than drawing conclusions from a brief test. For a detailed comparison, see On Demand and battery troubleshooting.
On Demand conditions are still met. Then determine whether the cause was the toggle, a network change, or a connection problem.If the problem only occurs after waking from sleep or switching networks, note the connection type before leaving and after returning, along with the VPN status shown by the system. Repeat the same scenario in manual mode: if that fails too, investigate the new network and proxy path first. Only narrow the issue to trigger timing and conditions if manual mode works.
04 Connectivity
Ping and Connectivity Test: interpreting results
Understand what the test measures and which target it uses
Ping and Connectivity Test help diagnose connectivity, but what a test actually measures depends on its method and target. A probe of a server address doesn’t prove that a site is reachable after the proxy connection is established. Successfully reaching a test address over one route doesn’t mean that route can access every service. In particular, don’t assume a test uses ICMP just because it displays a latency value. Check the method and target shown in the interface, along with the current network, before interpreting the numbers.
As a baseline, keep the app’s current test method and target, and collect a set of results under the same conditions. There’s no need to copy someone else’s test address or timeout. If the target service often times out or is only reachable on certain networks, comparing servers will be skewed by differences in the target. If you need a different target, choose one you’re authorized to access that responds over the route you want to test. If the test address requires DNS resolution, DNS problems can affect the result too; a latency label doesn’t rule that out.
Compare under the same conditions; don’t rank servers by one reading
For a practical comparison, stick to either Wi-Fi or cellular, pause large transfers that could use significant bandwidth, and note the selected server and mode. Run a few spaced-out tests against the same target to distinguish consistent failures, occasional timeouts, and generally slow responses. To compare two existing servers, use the same target and method at roughly the same time. A fast reading may reuse an existing connection; a slow one may reflect a change in Wi-Fi signal. Results can narrow down the cause, but they aren’t the only basis for choosing a configuration.
If the interface lets you adjust the timeout, start with the current value. Increase it slightly only if logs or actual requests show that responses arrive later and that delay is acceptable for your use. A longer timeout only delays the failure report; it can’t make an unreachable target accessible. A timeout that’s too short may mistake normal fluctuations for a disconnect. Record results before and after the change separately; success rates under different timeout thresholds aren’t directly comparable.
Consider latency and throughput separately. A latency test usually sends only a small number of requests and doesn’t show how stable a long transfer will be. If a large page stalls partway through, or short requests work while long connections repeatedly drop, use the latency result as supporting evidence and retest the same real-world scenario. Don’t use a private business link or a URL with access parameters as a test target; an address without private information is enough for most connectivity checks.
Use test results to narrow down the actual problem
If a test fails but real-world access works, check whether the failure is limited to the test target. There’s no need to change a working configuration based on one diagnostic result. If the test succeeds but an app fails, inspect the app’s actual request: can the domain resolve, did the expected rule match, and was the expected policy used? A page’s main document may load while its sign-in API or static resources fail. In that case, investigate the failed resource instead of repeatedly testing the homepage.
If every available server fails on the same network, first test a known-working direct connection to check local network access. If possible, then switch networks while keeping the server and settings unchanged and test again. If only one server has a problem, check whether its address, port, and protocol parameters from your provider are still valid. Don’t guess at unfamiliar settings; noting which stage failed is more useful than writing only “timeout.”
If you don’t have a baseline for a device, save a test record from a time when everything works. If intermittent problems arise later, use it to identify whether the network, target, or app configuration has changed. There’s no need to keep adjusting a working setup just to chase a lower latency number.
05 Request logs
Log: tracing DNS, rules, and connection issues by time
Capture logs briefly and reproduce one action
Use Log to find where a specific request failed, not to judge whether a configuration is working overall. As a rule, keep the current log level. If a problem occurs and the available information isn’t enough, temporarily increase the detail using the options shown in the interface. Note the original level first and restore it when you’re done; don’t leave verbose logging on by default. Available fields may vary by device. If a field isn’t shown, that doesn’t mean the corresponding step didn’t happen.
Before testing, note the current time, network, active configuration, and Global Routing mode. Close foreground apps or pages that generate lots of unrelated requests, then perform one easy-to-repeat action, such as reloading a public page. Note when you did it, then check the nearby log entries. Don’t update subscriptions, switch servers, or refresh other apps while reproducing the issue; multiple changes in the same time window make it difficult to identify which entry is relevant.
Read the failure stage, not just the last line
First check whether the target is identifiable, then look for clues such as a DNS result, a matched rule, a selected policy, or a connection error. If the log says the target couldn’t be resolved, check DNS and local mappings first. If the target is identified but the policy is unexpected, check the active file and rule order in Config. If the request took the expected proxy path but the connection failed, check whether that path is reachable and whether the protocol parameters match instead of adding rules to mask the symptom.
One action often generates several requests: the main document, images, sign-in checks, and other resources. Seeing DIRECT or REJECT on one entry doesn’t prove it caused the failure. First confirm that the entry’s target corresponds to the resource that failed, then repeat the same action. If only part of a page is broken, identify what’s missing instead of treating every request near the main domain’s timestamp as an error.
If you don’t see a new entry after reproducing the issue, first check whether the action generated a request. The app may have shown cached content or reused an existing connection. Then check the connection status, current mode, and available log range. An empty log alone can’t distinguish between no connection, no logging, or no new request from the app. A stable test action is usually more useful than clearing everything and blindly increasing the log level.
When comparing logs, preserve their time order and the conditions for each test. If the first log shows a DNS failure and the second a connection timeout, that doesn’t necessarily mean the problem got worse: DNS may have recovered, allowing the test to reach the connection stage for the first time. Conversely, a new log without errors doesn’t prove that everything works. If the app didn’t complete the expected task, confirm that it actually sent a request.
Share only the fields needed for diagnosis
Logs may contain domains, full URLs, query parameters, and internal addresses. They can also reveal server names or account-related information. When sharing a problem, include only the details needed to show when it happened, the mode, and the error type. Hide account identifiers, credentials, subscription links, and unnecessary addresses; don’t post the full original configuration. Check the surrounding context in screenshots too, so server names and unrelated requests aren’t visible in the corners.
When reporting an issue, you could write: “On the same Wi-Fi and server, the configuration mode fails while proxy mode works; confirmed the failed request matched a rule of a particular type.” This describes a reproducible behavior and is more useful than posting a single error line. Restore the original log level when you finish. If you keep a record for comparison, retain only a necessary, redacted summary. Check Frequently asked questions and Glossary for common scenarios and terminology.
If an issue happens only once and can’t be reproduced soon, don’t make broad setting changes based on incomplete logs. Note the original state and known facts. When it happens again, record the network and actual target so you can tell whether both incidents were the same problem.
06 Quick access
Widget: status and quick actions
Establish a reliable baseline in Home first
Use the Widget to check connection status or perform quick actions offered by the interface. It isn’t a place to configure routing, edit files, or inspect every request. There’s no need to add a widget before you’ve verified a manual connection. First check the server, mode, and connection result in Home, and test a real service. Then decide whether you want a shortcut in a location supported by the system. Widget availability, displayed information, and available actions depend on the current device’s system interface.
As a baseline, operate the app directly and add a widget only if needed. Don’t treat it as a prerequisite for using the client. Before adding one, decide what you need it for: if you only check the connection occasionally, choose a simpler view; if you want to make switching easier, choose an available version that supports the action you need. Adding a widget doesn’t change the app’s current configuration, and a widget that hasn’t appeared yet doesn’t mean the proxy connection failed.
After adding it, test one action and one status refresh
Find Shadowrocket in the system’s widget list, choose an available layout, and place it where you want. If it doesn’t appear in the list, check whether you’ve opened the app and whether the target location supports that layout, then reopen the system’s widget picker. Don’t reset DNS, subscriptions, or configuration files just because you can’t find the widget. The widget interface and the app’s network requests are separate; a missing widget doesn’t mean the app can’t connect.
Start from a known state. For example, confirm that Home shows as disconnected, then perform an available widget action once. If the action only opens the app, verify the result there. If it changes the connection directly, wait for the system status to update before checking a real service. Don’t tap repeatedly before the status refreshes; multiple actions can leave you back where you started, making it hard to tell whether the update was slow or the action didn’t register.
Test the reverse as well: change the connection state in Home, then check whether the widget updates. If they disagree, compare the current in-app state, system VPN status, and actual access. Widget updates may depend on when the system refreshes them; a status change doesn’t guarantee that every service is immediately reachable. For example, if it shows connected but a site still fails, investigate routing and request logs rather than removing and reinstalling the widget.
Keep automatic connections separate from manual actions
If the widget seems unable to disconnect, check whether On Demand is enabled. The system may reconnect because its conditions are met after you disconnect manually, so the final status still shows connected. To test the widget’s behavior, note and temporarily disable the On Demand conditions, then reproduce the issue on a stable network. Restore the original settings and test a normal usage scenario afterward. This helps distinguish an action that didn’t work from an automatic reconnection or delayed status update.
If only the display is stale, first check whether it updates after you reopen the app. Only then consider removing and adding the widget again. This applies to the system widget; it doesn’t require deleting app configurations or account details. After changing the layout, confirm that it still provides the shortcuts you need. A layout for switching connections and one that only shows a summary aren’t interchangeable just because they occupy the same spot.
On shared devices or screens that are often visible to others, check whether the preview reveals server notes or other information you don’t want to share. Use a simpler layout if one is available; otherwise, check the connection in Home. When moving to a new device, check the configuration and add the widget separately; neither confirms the other. If manual connections work in the app, you can set up the shortcut later.
Home status → system VPN status → actual access → Widget display. Find the first point where they differ before deciding what to change.07 Moving data between devices
iCloud: sync, restore, and overwrite limits
Check what syncs; don’t treat sync as a backup
When moving a configuration between iPhone and iPad, distinguish three steps: restoring an App Store purchase, importing data from iCloud or a file, and selecting and enabling a configuration in the app. The purchase record lets you get the client; it doesn’t automatically put the same active configuration on a new device. Saving a file to iCloud also doesn’t mean the app’s local server list, active state, shortcuts, and device-level toggles will all migrate. Check each separately.
If you already have a configuration, first review the available iCloud options in Settings, then check your system account, iCloud permissions, and network connection. Don’t assume sync is enabled on a new device, or interpret a missing file as proof that data is lost. Before enabling it, check which data the interface says will sync. If a specific item isn’t clearly listed, plan to verify it again on the target device. In particular, don’t assume On Demand conditions tied to the network, system permissions, or widgets have been restored just because a file is in the cloud.
The recommended approach depends on how you use your devices. If you use just one device, you can keep the current settings. If you’re migrating, first identify which device has the complete version you want to keep, then use the available export, import, or sync options. Save an independent, recoverable copy of important data. Ongoing sync can propagate deletions and overwrites too, so seeing a file on another device doesn’t guarantee you can recover it if it’s deleted accidentally.
Migrate by source, contents, and enabled status
On the source device, note the active file, selected server, and mode. Distinguish configurations edited locally from subscriptions obtained from your provider. If the original configuration uses separately saved rule files or remote references, confirm that the target device can access them. Having the main file doesn’t mean all its dependencies are available. Don’t edit the same-named item on both devices before migrating; names can match even when the contents and import dates differ.
Once an imported item appears on the target device, open it and check a few recognizable details, such as a rule you added, a clear fallback policy, or the correct server note. If the interface offers Import from Cloud JSON, use a data format supported by that option. Don’t change an arbitrary .conf file’s extension and try to import it as JSON. Different import options may handle different data. Check the result, select the file you want to enable, then return to Home and verify the connection manually.
If files with the same name conflict, keep both copies first rather than overwriting the source with whichever one appears most recent. Compare active rules, DNS overrides, and dependencies to identify the one you need, then enable it on the target device. Don’t enable automatic triggers before testing the connection. Once the public or internal targets you need work as expected, adjust On Demand conditions for the new device’s usage. Don’t blindly carry over temporary exclusions from the old device.
Use one test item to check whether sync is working
If you’re unsure about the sync direction or timing, try a test configuration without credentials. Make a small, easy-to-spot change on one device and check whether it appears on the other. If it doesn’t, first check that both devices use the same account, the app has permission, the file is in the sync scope, and the network is working. Don’t try to force sync by repeatedly signing in and out, deleting real configurations, or editing on both devices at once.
Treat files containing server credentials or private subscription addresses as sensitive. Handle them only between accounts and devices you control, and don’t put configurations in publicly shared folders. Before exporting, check what the file will include. After importing, decide whether to keep any temporary copies and where to store them. Don’t rush to clean up the source device until the migration is stable; the original gives you something to compare against if rules go missing or sync overwrites data.
If a server appears on the target device but won’t connect, first check the credentials, current network, and required permissions before assuming iCloud sync missed something. Track “file is visible,” “contents are correct,” and “works in practice” separately to see which step needs fixing.
08 Local listening
Proxy ports: listening address, protocol, and scope
Distinguish remote server ports, local ports, and routing modes
The port entered in Add Server or the server details is where the remote server accepts connections. Get it along with the protocol settings from your provider. If Settings offers a Proxy listener, its port is where this device accepts proxy requests for apps or devices that need to connect to it. Proxy under Global Routing is a traffic-handling mode, not a port setting; it doesn’t change a remote port into a local one. All three involve proxy settings, so distinguish them by where they appear in the interface when troubleshooting.
If you only use the system VPN connection on this device, leave local listener settings unchanged and don’t enable an entry for other devices. Don’t set a fixed port or copy a number from an example unless you have a specific need. Use the value shown in the interface and verify the actual listener status. If the app doesn’t show a type of listener, don’t assume that a corresponding address or default port exists. Check the listener protocol, address, and port only when an auxiliary app specifically requires a manually configured proxy.
Check the address, protocol, and port together
If a listener is bound only to a loopback address such as 127.0.0.1, only this device can connect to it using that address. If another device uses its own 127.0.0.1, it connects to itself, not to the device running Shadowrocket. This often results in an immediate refusal or an endless wait. First check whether both ends are on the same device, then decide whether the listener’s scope needs to change. Don’t expose the service to every network just to fix an incorrectly entered address.
The same port number doesn’t mean the protocols match. An app that needs HTTP can’t connect to an entry that only accepts SOCKS5 just because the port number is the same. Likewise, a reachable local port doesn’t prove that the remote server or target is available. First check that the requesting app supports a protocol offered by the interface, then test with a target that contains no private parameters. If the local port is reachable but the request fails, investigate protocol negotiation and the outbound policy instead of repeatedly trying new port numbers.
Port conflicts can occur when another process on the same device is already using the same listening address and port. If the interface says it can’t listen, or the new entry won’t connect after you save the settings, check whether an existing service is using that address and port. If you need to change it, choose an available port you’re authorized to use, note the old value, and update every dependent app. Changing only the listening side leaves the client with its old settings, making the issue look like a proxy failure when it’s actually connecting to the previous address.
Allow access from other devices only within trusted networks
If you need access from another device, first check that the app explicitly supports the required listening method, that system permissions allow it, and that the network allows devices on the same LAN to communicate. Don’t expose a local listener to the public internet or enable port forwarding on your router. Public Wi-Fi and guest networks may isolate connected devices; seeing the same network name on two devices doesn’t mean they can reach each other. If the network policy prohibits device-to-device access, use an approved network instead of trying to bypass the restriction.
When a device joins a different network, its local IP address may change. An old address can be correctly formatted but no longer point to this device. If requests from another device fail while local access works, check that the connecting device is using the current address, then check the listener scope and network permissions. If the app can’t restrict access to the sources you need, keep the listener local or disable sharing rather than using a temporary test setup for everyday use.
When you’re done testing from another device, turn off any temporarily enabled listener or sharing option and remove the old settings saved by the connecting app. Keep a brief note without private addresses, recording the protocol, connection scope, and failure stage. If an app on desktop or mobile reports an issue later, use the note to check whether it depends on that listener before troubleshooting the app’s settings or request.