Shadowrocket Troubleshooting Guide

01 VPN switch won’t turn on: check VPN configuration authorization

First, identify which of these three behaviors you see: a system authorization prompt appears after you tap the switch; the switch turns on briefly and then turns off; or the interface shows it as on, but the system does not maintain a stable connection. These point to incomplete authorization, a connection process that has stopped, or a connection status that needs verification. Don’t assume all three mean the server is down. Disconnect any other active VPN, return to Shadowrocket’s Home screen, confirm that a valid server is selected, then try again and note the exact message on screen.

Complete the system authorization prompt

The first connection requires system permission to add a VPN configuration. This prompt creates a system-managed connection profile; it does not confirm that the server is reachable. Check the app name in the prompt, make sure it was triggered by Shadowrocket, and complete any device authentication required by the system. If you dismissed the prompt, return to the app and try connecting again. Avoid changing other settings before authorization is complete, or it may be difficult to tell whether the failure occurred before or after authorization.

Next, open system Settings and check the VPN section for the corresponding configuration. Menu names may vary by system version; search Settings for VPN if needed. Finding a configuration only means the system saved the connection entry—it does not prove the current server is available. If no configuration appears, trigger authorization again. If the device is managed by an organization or the relevant options are unavailable, ask the device administrator about restrictions instead of changing the server password.

If the switch turns off immediately, separate system issues from configuration issues

Turn off On Demand, then try connecting manually and see whether it still disconnects immediately. On Demand conditions can change the connection state when the network changes; disabling them helps rule out automatic behavior. Note the name of the active Config and check for recently edited invalid content, references to missing policies, or incomplete fields. If possible, restore your own last known working configuration rather than replacing the entire setup with one from an unknown source.

If the connection worked before and the issue began only after deleting the system VPN configuration, you can trigger system authorization again through the app after confirming you have the necessary configuration backup. Deleting the system configuration is not a first-line fix: it will not correct invalid server parameters or restore subscription details. If you need to recreate it, disconnect first and note the On Demand state. Remove only the configuration for Shadowrocket, taking care not to affect other system entries used for work.

End this troubleshooting round with an observable result

After authorization, keep the app in the foreground and check that the system VPN status remains stable. Then open a regular webpage that worked before. If the switch stays on but the page fails, continue to the next section on routing and servers; don’t repeatedly delete the authorization. If the switch still turns off immediately, record the exact error, whether it happens with every server, and whether it recurs after restarting the device. A normal restart followed by another test is more informative than repeatedly force-quitting the app.

Check system restrictions separately: Screen Time, device management policies, or other network configurations may affect VPN connections. Review only authorization settings relevant to your device, and do not remove organization-managed configurations. If ordinary network access is unavailable even with the VPN off, restore Wi-Fi or cellular connectivity first; VPN authorization cannot replace a working internet connection. For more about permission prompts, see About the Add VPN Configuration prompt.

02 No internet after connecting: check routing and the underlying network separately

A system VPN status of Connected means the connection extension is running; it does not mean every request reaches its destination. Turn off Shadowrocket and try a known working webpage on the same network. If it still fails, check whether Wi-Fi requires a captive portal login, cellular data is available, and the router has internet access. On public Wi-Fi, complete the network’s login or terms acceptance before connecting so a blocked sign-in page isn’t mistaken for a rule issue.

Use Global Routing to identify where the problem lies

Once the underlying network is working, note the current Global Routing mode and briefly compare results for the same target. Config routes traffic according to the current rules; Proxy checks whether the selected server can carry the request; Direct checks access without a proxy server. These modes are diagnostic tools, not permanent fixes. Restore the original mode after each test so later app requests follow the expected route.

Use the same target in all three modes; don’t test different websites in each. A single site failing does not prove the whole connection is broken—the site itself may be down, or its content may depend on other domains. Test at least one other independent target and note whether nothing loads, only images fail, or the login step fails. If Proxy works but Config does not, check which rule matched the request instead of changing server protocols.

Rules match from top to bottom: find the rule that actually matched

Inspect the active Config, not just the most recently edited file in the list. Rules are generally evaluated from top to bottom, and the first match determines how a request is handled; a broad rule lower down cannot correct a policy already selected by an earlier rule. Pay particular attention to the broad scope of DOMAIN-KEYWORD, whether REJECT is blocking traffic unintentionally, and whether FINAL behaves as expected. The example below illustrates matching syntax and order; it is not a recommendation to replace your existing configuration.

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

If logs are available, inspect one request you just made and compare its target domain, matched rule, final policy, and error. The selected server name alone may not reveal the actual route; rules or policy groups can change the exit path. If the request matched REJECT, first check whether that domain was meant to be blocked. If it is required for your task, adjust only the relevant narrow rule and preserve its original value. Don’t clear the entire rule set just to make one page load.

Choose the next section based on reproducible results

If every mode fails but access works with the connection off, continue to the DNS and connection-process sections. If only Proxy fails, see Server timeouts. If only Config fails, focus on rules and policy references. If a local printer or router admin page is unreachable, check that the target address is on your local subnet and whether an existing IP-CIDR rule covers it. Don’t assume the example private subnets cover every home network.

The final check should repeat the action that failed, not just confirm that a webpage title appears. Reload the page, make a necessary ordinary request, and confirm that the system connection remains stable. Before logging in or paying, verify that the website address is correct; don’t disable certificate validation to address a page error. If you still can’t identify the cause, compare the symptoms in the FAQ and keep the results from all three routing modes so you don’t repeat the tests from scratch.

03 Server timeouts: check the address, transport, and authentication in sequence

A timeout means the expected response did not arrive within the allotted time; it doesn’t identify which part failed. The server domain may not resolve, the destination port may be unreachable, the protocol handshake may not match, or the target used by Connectivity Test may be temporarily unavailable. Record where you ran the test, the exact error, whether only one server fails, and whether real webpage requests fail too. A test result is a clue, not a complete measure of server status.

Check the basic fields in Add Server first

Open the existing server entry and compare it field by field with the original information you have: Type, Server, Port, and authentication details. Don’t put a path, spaces, or a protocol prefix in Server unless they belong in that field. Port must match the port the server actually listens on. When entering details manually, it’s easy to mistake a display name for a server address or paste a subscription URL into a single-server field. Confirm what kind of information you have before editing it, rather than repeatedly pasting it into the wrong place.

If the address uses a domain name, failed DNS resolution can prevent the connection from starting at all. Check whether other domains resolve on the same network, then see the DNS section. Don’t replace the domain with a random IP address you found: the server may depend on SNI, a certificate domain, or specific routing. Testing with an IP is meaningful only if you know how it maps to your server and preserve the correct TLS parameters.

The same protocol does not mean the same additional parameters

For Shadowsocks, check the encryption method and password. For VMess and VLESS, verify the ID fields and transport. For Trojan, check the password, TLS, and SNI. With Hysteria2, check whether the current network supports the required UDP traffic. If using a transport such as WebSocket, Host and Path must also match the server configuration. Changing Type alone won’t make different protocols interoperate, and a port number by itself does not identify a protocol.

For certificate errors, first check the device date and whether SNI matches the certificate domain, then confirm the server certificate is valid. Don’t treat Allow Insecure as a general fix; bypassing validation can hide an incorrect address or an invalid certificate. A TLS connection to a port does not prove authentication succeeded or that the request reached the intended server. For field definitions, see Trojan parameters and TLS checks.

Use the fewest comparisons needed to identify the network boundary

If possible, keep the same server configuration and test on both Wi-Fi and cellular. If only one network fails, investigate that network or route first rather than regenerating all authentication details. If only one server fails on the same network, focus on that entry’s address, port, and server status. After switching networks, wait for the connection to stabilize before sending the same request, so a brief handoff interruption isn’t mistaken for a persistent failure.

If a manually added entry works but the same entry from a subscription does not, compare their fields one by one; subscription updates may overwrite local changes. If every existing server fails, don’t assume the app is damaged: the servers may share a domain, credentials, or service endpoint. When contacting your own service provider, include the time, network type, protocol, and a redacted error; never post full credentials publicly. After correcting the issue, test a real request rather than just looking for a number in the test list.

04 Subscribe failures: distinguish retrieval, parsing, and overwriting

Subscription issues have at least three stages: whether the app can retrieve the content, whether it can recognize the response, and whether the imported entries appear as expected. If the first stage fails, repeatedly changing server protocols won’t help. If the content imports but the connection fails, see the previous section. This section assumes you already have your own subscription. A subscription URL is an access credential; even if it looks like an ordinary web address, don’t show it in screenshots, public logs, or instructions others can copy.

Check the complete address before investigating how it is retrieved

In the relevant Subscribe area in Config, check the address you already have and make sure copying did not omit query parameters, truncate the end, or add a line break. If the app provides an edit or update option for subscription entries, follow the wording in the installed interface; names and locations can vary by entry point and version. Don’t use a service information page, account login page, or single-server share as a subscription URL. If you’re unsure what kind of address you have, confirm with its original provider first.

When an update fails, note whether the connection was on or off. Retrieving a subscription also requires a network path, so an unavailable current server may prevent the update request from reaching its destination. If the underlying network is available, briefly turn off the connection and try again. If retrieval requires an already working route, use an entry you have verified yourself. Avoid repeated rapid retries, which can compound a temporary rate limit with the original problem.

A successful response does not mean the content is a valid subscription

A network request may return a login page, expiration notice, verification page, or error message instead of subscription data. In that case, “unable to parse” usually does not mean the app needs an arbitrary format conversion; the response itself is not the expected server data. Check whether your subscription is still valid, whether its address changed, and whether the provider changed the response format. Don’t overwrite your active Config with unknown webpage content or submit subscription credentials to an unfamiliar online conversion service.

If some entries import but others are missing, compare the missing entries’ protocol types, required fields, and support in the current app. Don’t invent passwords or IDs, or keep changing encodings at random. Describe the issue using redacted field names and error text rather than sharing the raw response. For a comparison of import options, see Subscribe, Add Server, QR code, and clipboard import options.

Protect local edits before updating; check the selected server afterward

A subscription usually represents information managed remotely. An update may change names, order, addresses, or the number of entries, and locally edited parameters may not persist. Before updating, note which fields you changed and, if needed, save a configuration backup supported by the app. Afterward, check that the previously selected server is still there, then verify Global Routing and the active Config. A successful list refresh does not mean the selected entry is now usable.

If the list becomes empty after an update, don’t immediately delete all previous entries. First check that you selected the right subscription, that it did not return empty content, whether account status changed, and whether a local record can be restored. If an existing manually added entry still works, keep it as a baseline. Deleting and adding again is appropriate only when you have complete original details and can retrieve the content again; it is not a universal fix for parsing errors.

After updating, choose a server entry, check its required parameters, and test the same ordinary webpage. If the subscription updates successfully but the server times out, stop retrying Subscribe and investigate the connection parameters. If only automatic updates fail while manual updates work, note the network state and timing; don’t assume the background mechanism is broken. The app purchase and subscription validity are separate—buying the app again won’t fix an expired subscription URL.

05 Slow speeds: distinguish handshake delays, throughput, and the destination service

“Slow” can mean a long wait before a page opens, a page that responds quickly but transfers large files slowly, or a problem limited to images, video, or one app. Describe the symptom in a repeatable way: how long the same target takes to load the first time, whether the second attempt is faster, and whether switching networks changes the result. Don’t treat Connectivity Test results as download speeds. Round-trip time for a short request and sustained transfer capacity are different measures; one test cannot account for congestion, packet loss, or load on the destination service.

Set up a comparable test

Use the same device, network, and target, and run comparisons at roughly the same time. Pause cloud sync, large transfers, or app updates so other tasks don’t use the network. Note the current server and Global Routing mode, then compare the first and repeated visits. If the first is slow but the next is much faster, DNS, TLS handshake, or content caching may be involved. If transfers remain slow, focus on path quality, congestion, and the server’s actual capacity.

Don’t change servers, DNS, and rules at the same time and then compare results—you won’t know which change helped. If you have several servers you manage, switch one at a time and repeat the same request. Don’t count a brief interruption during a network handoff as the steady-state speed. Wait for Wi-Fi or cellular connectivity to stabilize and finish any network authentication before starting the next test, so the result is meaningful.

If only some content is slow, check domains and policies

A webpage may request content from several domains, including the main site, static assets, images, and APIs. If the main page is fast but its assets are slow, those domains may match a different policy or a broad rule may change the exit route. Check recent request records for the slow request’s actual domain and matched policy. Change only rules confirmed to be wrong; don’t route every related domain the same way. The destination service may also serve different content based on region, account, or cache, so a successful server test alone does not rule out differences at the destination.

If Config is slow but Proxy works, check policy groups, rule order, and the DNS query path. If both are slow but Direct works for the same reachable target, investigate the current server route. A Direct failure does not show that the server is faster or slower: the two routes may not have the same reachability. A valid comparison requires the same action to succeed through both modes.

Don’t adjust UDP, MTU, or transport parameters blindly

Real-time communications, some streaming services, and specific protocols may depend on UDP; ordinary webpages working does not prove the UDP path is healthy. If only these features fail, check server support and restrictions on the current network. For protocols such as Hysteria2, changing a bandwidth field is no substitute for confirming basic connectivity; a larger value does not guarantee higher throughput. Follow your own server’s configuration guidance, preserve the original value, and test one variable at a time.

If small requests work but large ones stall, path MTU may be worth investigating, but don’t change it repeatedly without evidence. Packet loss, destination rate limits, or connection resets can look similar. First note whether the issue occurs on only one network, is tied to a specific protocol, or disappears when you switch to another server you already know works. Adjust parameters to match the deployment only after confirming a connection and understanding how to restore the original value.

Device heat can also affect performance. Sustained high-load transfers, a screen that stays on, and background tasks may all contribute. Pause testing and let the device return to a normal state before trying a short request again. Don’t run repeated speed tests while the device is noticeably hot. Judge the result by the original task: whether a page loads promptly, video plays without constant buffering, or a file transfers steadily—not by chasing a lower number in a test screen.

06 DNS issues: identify where resolution comes from and where requests go

DNS translates domain names into addresses used to make connections. If a domain can’t be resolved, the proxy handshake may not have started. If it resolves to an address unsuitable for the current route, you may see a timeout or reach the wrong destination. Common clues include several domains failing at once, a long delay on the first visit, or some targets failing after a network switch. A single reachable IP does not prove that every issue is DNS-related; HTTPS also relies on the domain, SNI, and certificate validation.

Check the active Config, not what you remember setting

Open the configuration currently in use and check dns-server under General, along with any mappings or rules that affect resolution. The example below indicates use of the system-provided resolver; it illustrates syntax and is not guaranteed to suit every network. Save the current value before changing it, especially if you already use split DNS. System DNS sources can change with Wi-Fi, cellular, and device management settings, so they are not necessarily fixed.

[General]
dns-server = system

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

Check for manual Host mappings or stale address entries. They may bypass the normal resolution path you’re investigating, making a dns-server change appear to have no effect. If a domain is pinned to an outdated address, compare it with your original configuration source before removing or correcting the entry. Don’t copy an address from a public discussion into a mapping; domain-to-address mappings can vary by region, deployment, and time.

Encrypted DNS still needs a reachable network path

With encrypted DNS, the resolver itself must be reachable. If accessing it requires a proxy, while the proxy server’s address depends on that same resolution path, there may be a dependency problem during startup. First check whether the server domain can be resolved initially, then investigate later destination domains. Don’t change the resolver and proxy address at the same time, or it will be difficult to tell whether resolution recovered or the server route changed.

Some public Wi-Fi networks require their own DNS and authentication flow. Changing DNS settings before signing in may not help. Turn off the connection, complete the network login, then reconnect using the original configuration and test again. If the issue occurs on only one network, compare the same configuration on another network you can use. If the result changes while the configuration stays the same, investigate how the network handles DNS requests rather than rewriting all domain rules.

Consider IPv4, IPv6, and rule matching together

A domain can return both IPv4 and IPv6 addresses, and the actual route chosen by the device depends on network support. If the issue occurs only on a network with IPv6, record the address type returned, the actual connection target, and how the request failed instead of disabling IPv6 globally. IP-CIDR and IP-CIDR6 handle different address families; a local rule for the former may not cover the latter. Domain rules and IP address rules also match at different stages, so identify the rule that actually matched before making changes.

GEOIP relies on address location data and does not precisely describe the purpose of every domain. CDN addresses can change, and shared addresses may serve multiple domains. For a small number of specific needs, check whether a more precise DOMAIN or DOMAIN-SUFFIX rule will work rather than continually broadening an address range. Keep FINAL as an understandable fallback and confirm that the policy fits your current use.

After changing a setting, repeat the failed request, keeping in mind that the app or system may still have cached data. Close and reopen the relevant page, then check the new request. If reconnecting is necessary, record the settings before and after disconnecting. Don’t restart every device repeatedly instead of testing. Success means the domain resolves appropriately, the request follows the expected policy, and the operation completes—not just that a DNS test reports success. For keyword definitions, see the Glossary.

07 Battery drain, heat, and frequent reconnects: identify what is active

Keeping a VPN connected for a long time does not necessarily mean it is using excessive power. Check data transfer, reconnect frequency, device temperature, and activity from other apps during the same period. The system battery screen summarizes activity over time; it does not show the exact cost of one request. Note when the issue began, the network and apps in use, then compare similar tasks over a similar period. A high percentage in one battery summary does not by itself mean the app was continuously under heavy load.

First rule out continuous transfers and background activity

Check for photo syncing, large file transfers, video playback, or app updates. When these tasks use the connection, the network extension may process traffic continuously, so check activity for both the app doing the work and the connection extension. Pause the tasks and keep other conditions the same while you observe the device for a while. Don’t run repeated Connectivity Tests during battery checks; they generate connections and data traffic themselves.

Interpret background activity on the system battery screen in context. A screen that stays on, weak cellular signal, hotspot sharing, and hot surroundings can all increase power use. Compare again when the device is at a normal temperature and the network is stable. If the device continues to heat up with the connection off, investigate the device and other app activity instead of attributing everything to Shadowrocket rules.

Test On Demand and network switching separately

On Demand connects according to system conditions. Frequent switching between Wi-Fi and cellular, or brief loss of an access point, can trigger repeated connection and disconnection attempts. Note the current On Demand conditions, then temporarily turn off On Demand and connect manually on the same network to see whether reconnects decrease. If they do, check for overlapping conditions and network instability instead of leaving a trigger configuration enabled without understanding it.

A brief reconnect after waking from sleep, leaving Wi-Fi coverage, or passing through network authentication may result from an environmental change. The concern is repeated reconnecting after the network has stabilized. Check whether the logs show a system-triggered connection, a failed server handshake, or repeated retries from an app. Distinguishing these will show whether to adjust On Demand, investigate the server, or address an app that keeps sending requests. A flashing status icon alone is not enough.

Logs, rules, and the cost of failed connections

If you enable more detailed logging to troubleshoot, return to your usual log level after capturing the relevant event. Keeping extensive logs for a long time uses storage and processing resources and may expose private information. Collect logs around one short, reproducible incident rather than saving every routine request. Before sharing, redact identifying domain details, server addresses, and credentials; keep only the error context needed to investigate.

An unavailable server can also make requests wait and retry repeatedly. If the active rules direct lots of routine traffic to an unavailable policy, the apparent battery issue may actually be ongoing connection failures. First verify that the selected server works, then check whether a domain is being blocked incorrectly and repeatedly retried. A large number of rules alone does not prove they are draining the battery; use actual requests, failure frequency, and before-and-after comparisons as evidence.

If only one protocol keeps reconnecting on the current network, compare it with another working configuration you already have, keeping the target and task the same. Don’t change the protocol, server, and workload together and then attribute the result to one setting. For entries such as WireGuard that depend on deployment-specific parameters, don’t adjust keepalive values at random; the right setting depends on the server and network.

At the end of a test, restore your normal log level, confirm that On Demand is back to its intended state, and note any change in device temperature or battery trend. If the problem persists despite pausing background tasks, using a stable network, and testing a working server, keep redacted notes and continue with the post-update checks. Battery data covers a time window; allow a comparable period after changes rather than expecting a switch to change the historical percentage in a few seconds.

08 Issues after an update and on iPad: restore a baseline, then check what changed

An issue that begins after an update is not necessarily caused by the update alone. App updates, system updates, subscription refreshes, server changes, and network switches may happen around the same time. List the changes between the last successful connection and the first failure, then test again while changing as few variables as possible. Preserve the current Config and original server details; don’t clear all data immediately. Restoring a purchase restores app eligibility; it does not automatically restore all locally edited content.

After an update, confirm the selected server and system authorization first

Open Home and check the selected server, Global Routing, and system connection status. Then confirm that the active Config is still the file you expect. If you used a policy group, check whether its selection changed. A configuration appearing in the list does not mean it is active, and similar names do not guarantee matching content. Compare with your own known working baseline and change settings only after identifying the difference; resetting everything to defaults is not a substitute for diagnosis.

If the system VPN configuration was removed or the device needs authorization again after migration, follow the first section to complete the system prompt. If the app opens but all connections fail, turn off the connection and check basic access on the current network, then test with a server that worked before. If needed, restart the device normally and test once more, recording the result. Check update details and system requirements on the App Store page rather than relying on old screenshots in online articles to decide whether the current interface is “missing a feature.”

When comparing iPad and iPhone, make the conditions match first

If the same existing subscription works on iPhone but not iPad, first confirm that both devices are actually using the same server, protocol parameters, and Config. Matching subscription names don’t mean both devices have the same latest content. Also check Global Routing and DNS, particularly if one device has local edits. Don’t assume an iPad-specific compatibility issue before comparing each setting.

Network conditions may differ too: an iPad may use Wi-Fi while an iPhone is actually using cellular data. Connect both devices to the same Wi-Fi and test the same target, then compare the results. If only the iPad fails, check its VPN authorization, device management restrictions, network authentication, and system date. If both devices fail, investigate the shared server, subscription, or router instead of continuing to troubleshoot the tablet layout.

On iPad, landscape orientation, Split View, or window layout can move controls, but fields with the same name do not represent different server parameters. Look for features using interface labels such as Home, Config, and Settings. If there isn’t enough room, restore a full-size window before checking. Don’t create a duplicate configuration just because a control isn’t where it appeared in an iPhone screenshot. For initial setup, follow Getting Started; this page covers differences and problems.

Before reinstalling the app, understand backups and purchase recovery

If you need to reinstall the app, use the App Store only. First check the original purchasing account and purchased items; see Restore a previous purchase for details. Verify the developer name, Shadow Launch Technology Limited, the official icon, and app ID 932747118. Shadowrocket is a closed-source commercial app. Check system requirements and device eligibility on the App Store page; don’t infer eligibility for every device from older instructions.

Before reinstalling, make sure you have a recoverable copy of your existing subscription address, manual server parameters, and local Config. Backups may contain passwords, private keys, and access credentials; store them somewhere you control and don’t post them publicly. App purchase records, the system VPN configuration, and your own connection data are separate layers. Restoring the purchase does not prove the other two have been restored. After reopening the app, repeat the first-time authorization and verification steps.

Create a reproducible troubleshooting report

If these steps don’t resolve the issue, prepare a brief report: device type, system and app details as displayed, network type, where the failure occurs, redacted error text, last successful action, and comparison results you have already verified. Specify whether the switch turns off, DNS resolution fails, the handshake fails, or a particular request times out. Don’t just say “it stopped working after an update,” and don’t send a large batch of unrelated screenshots that obscures the failing step.

For server authentication, subscription validity, or server-side protocol parameters, confirm the details with the provider of your own information. For system authorization or device management restrictions, check the device settings. After restoring service, verify that On Demand, Global Routing, log level, and temporary test rules are back to their intended settings. Troubleshooting is complete when the original task works repeatedly with the recorded working configuration—not when a webpage happens to load once.