Shadowrocket Troubleshooting Guide

01 / CONNECTION

Switch Won't Turn On: Check System Authorization First

This section covers cases where tapping the connection switch on Home immediately turns it off again, a system authorization prompt keeps reappearing, or the expected connection status never appears. Don't change servers yet: turning on the switch and getting a response from a remote server are separate issues. First confirm that the device can access ordinary websites over its current Wi-Fi or cellular network, then turn off the Shadowrocket switch and start by checking system authorization. If the device cannot connect to any network, troubleshoot its network connection before changing settings in the app.

Check First-Time Authorization and System Status

When you turn it on for the first time, the system may ask you to allow a VPN configuration. Follow the prompt, then return to Home and try again. If you previously dismissed the prompt, check the VPN-related configuration status in the device's system settings, then return to the app and trigger authorization again. Menu locations in system settings can vary by device and interface, so don't rely on one fixed path. A system-level connection indicator only means the configuration is enabled; it doesn't confirm that a server is working. Open a webpage to verify the connection.

If tapping the switch produces no system response, quit and reopen the app, then check whether the system is waiting for an authorization prompt to be handled. Restarting the device and trying again can help distinguish a temporary system state from an ongoing configuration issue. Before each test, note whether the switch “won't stay on” or “is on, but webpages won't load.” The latter points to the next section: check routing and servers instead of repeatedly revoking authorization that has already been granted.

Isolate the Connection Configuration

After confirming system authorization, check on Home that the selected item is a server or subscription you already have and that its information is complete. Selecting a blank item, a deleted reference, or an outdated configuration may let you operate the switch without establishing a usable connection. If you recently imported multiple configurations, test just one at a time and note the original names before making changes. Don't change Global Routing while reimporting a subscription; otherwise, you won't know which change made a difference.

Also check whether On Demand has a trigger condition for the current network. For example, a rule that disconnects on a particular Wi-Fi network may conflict with manual operation when you're connected to that network. Temporarily disable automatic On Demand triggers, turn the connection on manually, and observe the result. Restore the original settings afterward. If the device is managed by your workplace or school, its VPN configuration restrictions may affect operation. Ask the device administrator what is allowed instead of repeatedly adding the same configuration.

02 / ROUTING

No Internet After Connecting: Separate Network, Server, and Rules

This section covers cases where the switch stays on but browsers or other apps fail to load. Separate three things: the device's connection to the network, its connection to the selected server, and how rules handle requests. Turn off the connection and open a normally accessible page over the same network. If it still fails, check the Wi-Fi or cellular connection first. If it works with the connection off but fails when it's on, check the server and Global Routing in the app. Use the same test page each time to avoid drawing the wrong conclusion from changes in the website itself.

Narrow Down the Cause with Global Routing

Config, Proxy, and Direct in Global Routing use different routing modes. Config applies the rules in the configuration; Proxy routes requests through the selected proxy; Direct connects directly. Note the original setting, switch modes briefly for comparison, then restore it. If Direct works but Proxy doesn't, check the selected server and its parameters. If Proxy works but Config doesn't, check rule order, policy names, and FINAL. If all three fail, focus on the device's network, system connection status, and test destination. These comparisons help identify the cause; they aren't a reason to leave the app in a test mode.

Check the Selected Item and Scope of the Failure

Go to Home and check whether the selected server is from the expected subscription or manual configuration. A subscription update may change server names, order, or availability. A long list of entries doesn't prove that the currently selected one still works. Select another server you already have and previously used successfully, then repeat the same test. If only one server fails, check its address, port, and server status. If all entries fail, check the shared network, configuration, and DNS. A single latency result can't predict whether every webpage will load.

If only one website won't open, note its domain, the time of the failure, and the result under each Global Routing mode. If Config and Proxy behave differently, check the relevant DOMAIN, DOMAIN-SUFFIX, or FINAL rule. If a browser works but a particular app doesn't, check whether the app is requesting the domain you expect. If you can't identify the domain, use the diagnostic information available in the app before changing one rule and testing again. For the full initial connection sequence, see the user guide. For quick answers to common issues, see the FAQ.

03 / SERVER

Server Timeout: Distinguish a Failed Test from an Unavailable Server

This section covers timeouts in the server list, unexpected Connectivity Test results, or pages that remain unresponsive after you select a server. A test result reflects one check at a particular time and on a particular network; it doesn't necessarily reflect how every app will perform. Confirm that the network itself works, then repeat the test once on the same network and in the same location. Results can differ if the test destination isn't the same as the one you use day to day. Don't delete an entire subscription based on one timeout.

Check the Details First

For a manually added server, verify the protocol, server address, port, and required authentication details one by one. An extra space in the address, a mistyped port, or a mismatch between the protocol and server configuration can cause a timeout. Shadowsocks, VMess, VLESS, Trojan, WireGuard, and other protocols use different parameters. Check each field against the server information you already have; don't reuse settings from a different connection. After importing with Scan QR Code, check that the resulting entry matches the original details. A successful scan only means the content was recognized.

If the entry came from a subscription you already have, check whether the last update succeeded, then confirm that the selected entry is still valid after the update. An update may change server addresses or the order of entries, while an old manual copy remains in the list. To avoid confusion, note the name, group, and source, and test one clearly identified entry at a time. Don't post full passwords or tokens in public forums. You only need to check whether the fields match, not disclose their actual values.

Find Shared Causes with Cross-Testing

Keep the server the same and compare Wi-Fi with cellular. Then keep the network the same and test another server you already have. If one server times out on both networks, first check that server's configuration and status. If the same group of servers fails on just one network, check that network's access requirements, login page, and DNS. If all servers fail across different networks, revisit system connection status, subscription contents, and shared configuration. Change only one condition at a time so each cross-test gives you a result you can verify.

Latency tests can help identify entries that aren't responding, but a low number doesn't guarantee fast webpage loading. Once a connection is established, domain lookup, rule matching, and the destination site's response still matter. If the test returns a result but webpages keep failing, see routing troubleshooting and DNS troubleshooting. If tests keep timing out despite correct details, contact the provider of the server information you already have to check its status. For help interpreting test results when choosing a server, see Latency, Region, and Protocol Type.

04 / SUBSCRIBE

Subscription Import or Update Failed: Check the Link, Network, and Content

This section covers only subscription links you already have. An import failure, a failed update message, and a list that doesn't change after an update are three different issues. First confirm that you're working with a Subscribe-type subscription, not an individual server entry or a configuration file; they serve different purposes in the app. When copying a link, check for leading or trailing spaces, missing characters, and unexpected line breaks, especially if you copied it in pieces from a message. Links may contain sensitive credentials, so don't include them in public screenshots or support requests.

Check Whether the Link Still Returns Content

Before importing, confirm that the device is online; a subscription can't be retrieved if the network is down. If updates used to work but now fail, check whether the original link you have was replaced or its credentials changed, then ask the provider of that information to confirm it is still valid. Don't keep creating new Subscribe entries with the same name to retry. This leaves multiple similar groups and makes it hard to tell which one is selected. Keep the original entry, note the error, and try one manual update to make the result easier to compare.

An accessible link doesn't necessarily contain data the app can parse. If an update gets a response but the list is empty or clearly wrong, the returned format may not match the import method, or the response may be an error message instead of server data. Confirm that you copied the subscription endpoint, not an informational or login page. Don't enter a website page address as a Subscribe link. For Import from Cloud JSON or configuration imports, choose the appropriate import method for the content instead of treating everything as a subscription link.

Resolve Differences in the List Before and After an Update

After a manual update, check that entries appear in the expected group, then verify which server is actually selected. An update may change names and order. If new entries appear but an old manual entry remains selected, the connection won't improve automatically. If you have automatic updates enabled when opening the app, try a manual update first. If manual updates work but automatic ones are inconsistent, check whether the network was connected when you opened the app and whether Wi-Fi or cellular changed shortly beforehand. Automatic updates control when content is retrieved; they don't fix invalid links or data the app can't parse.

If you have multiple subscriptions, identify each group by its source, then update just one and compare changes to entry names and counts. Duplicate entries may come from repeated imports or from different subscriptions that return the same server. Check the source before deleting anything to avoid removing a configuration you still use. See How to Troubleshoot Subscription Update Failures and How to Organize Multiple Subscriptions. If just one manual server has stopped working, you don't need to refresh every subscription to troubleshoot it.

05 / PERFORMANCE

Slow Connections: Identify Which Step Is Slow

“Slow” can describe at least three different issues: a long wait before a page starts loading, slow transfer after it opens, or slowness limited to certain apps or websites. First note which one you're seeing and whether it happens on Wi-Fi, cellular, or both. Using the same device and test page, compare results with the connection off and on. If the device's network is congested, changing Shadowrocket settings alone won't fix the underlying network issue. Avoid pages that change frequently so the two tests remain comparable.

Separate Connection Setup from Content Loading

If nothing appears for a long time after you tap a link, the issue may involve DNS lookup, connection setup, or the server's response. If the page appears but images load slowly, look at transfer speed and the destination site's status instead. Use Connectivity Test to check the selected entry's basic response, then test with an actual webpage. The test result describes the check itself; it doesn't represent the full experience of loading video, images, or large files. If only one domain is slow, record how it behaves under Config, Proxy, and Direct rather than masking otherwise normal requests with a global change.

If you have multiple servers, keep the network and destination page the same and change only the server for each comparison. Distance, server load, protocol settings, and the destination site's response can all affect performance. Don't judge it by a region in the server name or a single latency test. If every server is slow on the same Wi-Fi but cellular is stable, first investigate the Wi-Fi's actual throughput, signal, and connection status. If just one server is consistently slow, check its details and server status.

Check for Differences Caused by Rules

When Global Routing is set to Config, rules determine the route for each request. An overly broad DOMAIN-SUFFIX rule might send a request that should use Direct through PROXY instead. Conversely, it might route a destination Direct when you intended to use the selected server. Identify the specific slow domain and check the first applicable rule. Make a narrowly scoped change without affecting other rules. Don't delete all rules and draw conclusions from one speed test; that changes how many unrelated requests are handled.

If the first request is slow only after the app has been in the background, distinguish the time needed to reconnect from ongoing transfer speed. On Demand conditions, switching from Wi-Fi to cellular, or waking the device from sleep can make the first request behave differently from later ones. Run two consecutive tests and note the difference. If only the first is slow, focus on connection triggers and network switching; if every test is slow, compare servers and DNS. For more guidance on choosing a server, see Server Latency and Real-World Performance.

06 / DNS & RULES

DNS and Rule Issues: Follow the Domain to Its Final Policy

Common symptoms include one domain failing to open, different results on different networks, or a failure in Config that works in Proxy. DNS resolves a domain to an address; rules determine how a request is handled. They're related, but they aren't the same setting. First check that the domain is correct and compare it with a page that has worked reliably. If only a specific domain is affected, note its full name, the current network, Global Routing mode, and matching rule. If every domain is affected, first rule out the shared causes covered in the network and server sections above.

Understand Top-to-Bottom Rule Matching

Configuration rules are checked from top to bottom. Once a rule matches, its policy applies and later rules don't handle that request. DOMAIN matches a full domain, DOMAIN-SUFFIX matches a domain suffix, and DOMAIN-KEYWORD matches a keyword. IP-CIDR, IP-CIDR6, and GEOIP apply to address-related conditions. FINAL handles requests that haven't matched an earlier rule and is generally placed at the end of the rule section. Check that each policy name exists in the current configuration; don't copy an example into a policy group that doesn't match it.

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

This snippet demonstrates syntax and order only: example.com is a sample domain, and PROXY and DIRECT are policy terms. It isn't a recommendation for every user's needs. If a broad DOMAIN-KEYWORD rule comes before a more specific DOMAIN rule, the latter may never take effect. If FINAL appears too early, later rules can't do their intended job. Save the current configuration before making changes, and move or edit one rule at a time. For a full example of priority and fallback behavior, see Rule Matching Order and FINAL.

Distinguish a DNS Lookup Failure from a Routing Error

If the browser says it can't find a domain, compare the results with the connection off and on, then under Config, Proxy, and Direct. If the same domain behaves differently across modes, check how DNS settings and rules affect it together. If other domains work on the same network, don't reset the entire configuration as a first step. Check DNS settings against your current network and existing configuration requirements: whether a custom address is no longer appropriate, whether results differ between networks, and whether the domain has a specific exception. Changing DNS isn't a universal fix for every timeout.

When using IP-CIDR or GEOIP, also check whether the rules can access the required address information. The text of a domain alone doesn't tell you which address rule will ultimately match. If a rule looks correct but traffic still uses a different policy, check whether a DOMAIN rule matched first or a broad rule appears earlier. Once you've found the cause, restore the temporary Global Routing setting and retest the affected destination and an unrelated website under Config to make sure the fix hasn't had unintended effects. For DNS definitions, see the quick reference.

07 / POWER

Excessive Battery Drain: Track Triggers and Background Activity

This section covers noticeably shorter battery life than usual while using Shadowrocket. Battery use is affected by screen brightness, cellular signal, background apps, frequent network changes, and other factors. A connection indicator that stays on doesn't prove that one particular setting is responsible. Check the device's battery usage information for app and activity breakdowns over the same period. Note the network type, whether you were moving, and whether the connection stayed on for a long time. Compare similar usage periods and scenarios instead of comparing intensive video use with idle time.

Check for Repeated Connections and Automatic Triggers

If the battery change coincides with frequent switching between Wi-Fi and cellular, check whether On Demand has overlapping conditions for Wi-Fi, Cellular, or Domain. Repeated connection, disconnection, and reconnection can increase network activity. Note the original conditions, temporarily disable automatic triggers, and connect manually for a comparable observation period. If the issue disappears, restore the conditions one at a time to find which one is triggering frequently in the current environment. On Demand controls when to connect; it isn't a universal fix for battery life.

If the connection repeatedly drops and server timeouts occur at the same time, check the network signal and server details first. A poor connection can generate repeated requests and increase activity; changing Global Routing alone may not address the cause. Test with the same server in a stable Wi-Fi location, then compare the results while moving. If the problem happens only in a certain location or along a particular route, note when the network changes. That's more reliable than comparing battery percentages by feel.

Review Usage and Retest Results

Check whether an app is continuously syncing in the background, transferring media, or making many data requests. Activity from Shadowrocket handling those requests differs from when apps are idle. Pause any clearly high-traffic tasks and check the battery information again over a similar period. Don't change DNS, subscriptions, and all rules at once: even if battery use drops, you won't know why. When comparing, record the original settings, change one item, retest under the same conditions, then decide whether to keep or revert it.

If the device becomes unusually hot or loses charge quickly even with the Shadowrocket connection off, the issue may not be limited to the current proxy configuration. Check the device system and other running apps first. If things return to normal with the connection off, record the connection conditions, network type, and test time, then check for repeated reconnections, On Demand conditions, and ongoing transfers. The goal is to identify a repeatable trigger, not to conclude from one idle test that a particular protocol or rule always saves battery.

08 / CHANGES

Problems After an Update: Check Whether the App, Configuration, or Network Changed

Before troubleshooting “it stopped working after an update,” clarify what was updated: Shadowrocket in the App Store, the device system, your existing subscription content, or a Config file you maintain. Each points to a different line of investigation. Note when it last worked and what happened before the issue appeared. Don't assume an update caused it just because the timing is close. Get and update the app through the App Store; check the App Store listing for compatibility and system requirements. To verify the developer and app ID on the store listing, see the authenticity guide.

Compare with the Last Known Working State

First test the device's network without Shadowrocket. Then check whether the Home switch stays on, and verify the currently selected server, Global Routing mode, and a consistent webpage. If the switch behaves differently than before, return to the system authorization section. If the switch works but all servers fail, return to the network and routing section. This layered approach is safer than immediately deleting all configurations and preserves the original state for further checks.

If the subscription changed, check whether server names, groups, addresses, or the selected item changed rather than relying only on an “update successful” message. If the Config changed, check whether new rules now precede old ones, whether FINAL is still in the right place, and whether referenced policy names exist. If you saved the original configuration, compare the specific differences and change only the item related to the problem. Don't combine configurations saved at different times by pasting them together; duplicate rules and invalid references make troubleshooting harder.

Keep Retest Results Reversible

Before changing settings, record the current selections, including the server, Global Routing, On Demand conditions, and custom DNS. After each change, retest the same page on the same network. If it doesn't help, revert that change before testing the next one. This avoids leaving multiple unverified settings in place even if the real cause is a network change. If the issue affects only one app, test the browser and the app separately, and note whether they use the same domain or network.

The App Store provides app information, but don't rely on a version number someone else posted to decide whether it applies. Use the store listing on your own device and the app's actual interface as your reference. If a system update brings up an authorization prompt, follow the system instructions, then test the switch again. If the problem began after a subscription update, start with checking the link and content. Record the update and the symptoms separately to identify which layer changed.

09 / IPAD

iPad Troubleshooting: Separate Layout from Connection Status

The basic troubleshooting steps in this guide apply to both iPad and iPhone, but screen layout, network access, and usage may differ. Don't look for a button in the exact same screen position as on iPhone. Use interface terms such as Home, Settings, and Global Routing to find the relevant features. First confirm that the iPad can access ordinary webpages over its current network, then check the Shadowrocket switch, selected server, and routing mode. If the issue happens only on iPad, compare network and configuration settings between the two devices before assuming a hardware fault.

Check Network Type and System Authorization

Some iPads are used mainly on Wi-Fi; others also use cellular. Check which networks are available on your device. If a connection fails on iPad, confirm that Wi-Fi access doesn't require a sign-in page or that the device hasn't just switched from another network. If the network isn't connected, Subscribe updates, Connectivity Test, and webpage access may all fail at once. System authorization is handled through system prompts. If the switch won't stay on, follow the steps in authorization troubleshooting; don't assume a failed subscription refresh is the only cause.

If a server you already use works on iPhone but not on iPad, make sure you're comparing the same server information, not just entries with the same name. The two devices may have subscriptions or manual copies imported at different times. Check the protocol, address, port, and source of the selected entry. Then test both devices on the same Wi-Fi to reduce network differences. If the iPad is using another Wi-Fi network, note that difference before comparing configurations.

Check Large-Screen Controls and Automatic Connection Conditions

The interface may rearrange when you rotate the iPad or use multiple windows, but Config, Proxy, and Direct mean the same thing in Global Routing. After changing a setting, return to Home to verify the selected item, then test the same destination. Don't select a different server by mistake just because the list moved. If access fails only after waking the device, check On Demand conditions for the current Wi-Fi or Domain and compare with a manual connection. If manual connection works but automatic connection doesn't behave as expected, focus on the trigger conditions rather than changing every server setting.

For steps to get a purchased app on another device and open it for the first time, see the iPad guide. Check the App Store listing for system requirements and compatibility. If subscription content differs between the iPad and another device, check each device's import and update results separately; changes on one device don't automatically update the other. Finally, compare using the same network, server information, and destination page. Only when these conditions match can you distinguish an iPad-specific issue from a general network or server problem.