Shadowrocket
Troubleshooting Guide

First distinguish between a toggle that immediately switches off and one that stays on while requests fail. For the first case, check the VPN configuration and system management restrictions. For the second, continue to the next section. Don't repeatedly delete the app.

Establish a repeatable baseline

Turn off Shadowrocket's connection toggle and temporarily disable other VPN configurations that may control network traffic. Then use a browser to open a site that normally works without a VPN. Public Wi-Fi may require you to sign in through a web page; seeing the Wi-Fi icon alone doesn't mean you're online. If the underlying network itself isn't working, complete the sign-in, reconnect, or contact the network administrator first. Changing servers or rules won't fix a problem with the underlying connection. Note whether you're using Wi-Fi or cellular, and whether the network, configuration, or system settings changed before the problem began.

Keep a brief record of your device and network type, whether the toggle stays on, the exact action that fails, and the full error message. “It doesn't work” isn't specific enough: an import failure, connection failure, and web page failure require different troubleshooting. During testing, keep the same known server and destination page, and pause unnecessary downloads. If you change the server, configuration, and network at once, you won't know which change helped—even if the issue goes away—and you'll have to start over next time.

Recheck VPN configuration permission

The first time you turn on a connection on iPhone or iPad, iOS asks to add a VPN configuration. Read the prompt and approve it on the device. If you previously canceled, turn the connection on again in Shadowrocket and look for the system prompt. Then open Settings and check that the corresponding VPN configuration appears. The path may vary by system version, so use Settings search rather than assuming an item is missing because an older guide shows a different menu. On a device managed by a school or workplace, a configuration profile may restrict VPN access; ask the administrator to confirm permissions instead of repeatedly reinstalling the app.

If the toggle still switches off immediately after permission is granted, restart the device and test again. Consider removing an old system VPN entry only if you've confirmed it belongs to Shadowrocket and backed up your app data; then let the app request a new configuration. The system VPN configuration is separate from the servers, Subscribe, and Config in the app. Removing one doesn't back up the others. Don't remove every profile or delete certificates and device-management entries unless you know what they do.

Rule out automatic triggers and connection conflicts

Check whether On Demand is connecting or disconnecting automatically based on network conditions. Note the existing conditions, temporarily disable automatic triggers, and test using the manual toggle only. If a manual connection works, restore the conditions one at a time and check whether the issue occurs only on a particular Wi-Fi network or during a network switch. The system may have more than one VPN entry; confirm which one is actually active. A connection indicator in the status bar alone doesn't prove Shadowrocket is handling requests correctly.

If the app won't open or closes immediately after launch, first save any configuration you can export, check available device storage, and confirm where to get the app on the download page. Get the iPhone / iPad version from the App Store; check the App Store listing for system requirements. The download page also covers installation and system approval for Mac, Windows, Android, and Linux. Don't replace the app with an installer from an unknown source while troubleshooting a connection issue. Once the app opens reliably and the toggle stays on, continue with network checks.

Compare the results in Direct and Proxy first, then check whether only Config fails. A connection indicator means the system has a VPN session; it doesn't mean every request has completed successfully.

Narrow down the issue with three modes

Keep a copy of your current Config and select a server you already have whose settings you can verify. Under Global Routing, test Config, Proxy, and Direct in turn, reopening the same web page after each change. Direct shows whether the destination is reachable without the selected proxy server; Proxy tests how that server handles the request; Config adds rule matching to the path. This comparison is for diagnosis, not a recommendation to use one mode permanently. Restore the setting that fits your needs when testing is done.

If Direct works but Proxy fails, check the server status, protocol settings, and remote connectivity first. If Proxy works but Config fails, check that the configuration is enabled, the rule order, and the policy each rule points to. If all three fail, confirm that the destination site is working, then check the underlying network and DNS. Some apps reuse existing connections, so close the old page and reopen it after switching modes. If needed, end the app's current session before testing so an old connection doesn't skew the result.

Check the active configuration, not just the list

In Config, confirm which configuration is actually enabled. A file appearing in the list doesn't mean it's in use; importing servers from a subscription doesn't switch you to the rules configuration you expect. Open the active file and review the Rule section from top to bottom. Usually, the first matching rule determines how a request is routed, so a broad rule near the top can prevent a more specific rule below it from taking effect. Before editing, make a copy and give it a distinct name so you can tell the original from the test configuration.

This example illustrates rule order only: send a specified domain to PROXY, route local network addresses through DIRECT, and handle other requests with FINAL. The server or policy assigned to PROXY must already be valid in your setup; this snippet doesn't create a server. GEOIP matching also depends on the address and related data, so don't assume a domain will produce the same result on every network. Don't replace a complete configuration containing necessary local rules with this example.

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

Check request matches when only some sites fail

If most sites work but one domain or app doesn't, check the rule that matched the request, the resulting policy, and any error message. A page may request its main domain, image domains, and API domains separately. If the page text appears but images keep loading, that doesn't necessarily mean the whole connection is down. Identify the failing domain before changing an individual rule. If a request matches REJECT, check what the rule is intended to do instead of deleting all reject rules; the original configuration may use them to block specific types of requests.

For local devices, printers, and internal sites, first confirm that the destination is on your current network and check whether its traffic is being sent through a remote proxy. Wi-Fi client isolation can also prevent devices from communicating; adding a DIRECT rule won't necessarily remove that restriction. If only one app reports a network error, check its system network permissions and service status too. After the issue is fixed, test the same destination in Config and remove temporary diagnostic rules, keeping only changes that are still needed.

A timeout means a test didn't finish within the allotted time. It may occur during address lookup, transport connection, protocol handshake, or the remote request. Start by checking the test type and the full error message.

Check whether one server or all servers are affected

In Home, run Connectivity Test on the servers you already have and note which ones fail. Then try opening a web page through one of them. Different tests check different stages: a successful port connection doesn't prove the credentials are correct, and one successful web page test doesn't guarantee that every request will work. If only one server fails, check its settings and remote status first. If all servers fail at once, check the current network, DNS, device time, and shared transport settings; don't rebuild every server one by one.

If possible, switch the same device to another known-working network while keeping the server and test destination unchanged. If the result changes with the network, the issue is more likely on the route between the local network and server, or in how the network handles that transport. A successful test on one network doesn't prove the configuration is entirely correct. Note whether the original network requires sign-in, filters traffic at the router, or fails only when busy. Repeatable differences are more useful for diagnosis than a one-off success.

Check each field against your existing server details

Open the editor for Add Server and compare the protocol, address, port, and authentication details with the server information you already have. Enter only the host name or address required by the address field; don't paste in a web URL's path. The port must match the server's listening port. Passwords, UUIDs, keys, and other authentication fields are protocol-specific and can't be substituted for one another. After pasting, check for spaces or line breaks at either end and for full-width punctuation. Visually similar characters copied from a chat or document can still cause a handshake failure.

For VMess, VLESS, Trojan, and similar configurations, check TLS, transport type, and related fields against the actual server requirements; settings aren't the same for every configuration. With WebSocket, the path and Host must match the server's requirements, including capitalization and the leading slash. With Hysteria2 or WireGuard, also consider how the current network handles UDP. A successful TCP test doesn't prove that UDP traffic will work. If you're unsure about a field, check with the provider of your existing configuration rather than copying settings from another server.

Check system time and handshake errors

An incorrect system date or time zone can affect certificate validity checks and authentication processes that depend on time. Turn on automatic date and time in system settings, confirm the displayed time is correct, and reconnect. If you see a certificate name mismatch or expiration error, check the server name, SNI, and remote certificate rather than disabling verification to hide the problem. A reachable address followed by repeated handshake failures gives more clues than a simple timeout. Record whether the error mentions a certificate, authentication, or transport response.

After checking local settings, if one server keeps failing on multiple working networks, share the protocol, failure stage, approximate test time, and a redacted error message with the provider of your existing service. Ask them to check the listener, authentication, and service status. Don't share passwords, UUIDs, full subscription URLs, or configuration QR codes. For a more detailed testing sequence, see Server Timeouts: Protocol Settings and System Time. Save a change only after confirming it helped, so failed attempts don't remain in your configuration.

A subscription update involves several stages: requesting the URL, receiving content, recognizing its format, and updating the list. A successful update doesn't mean a server is usable, and a failed server connection doesn't mean the subscription URL is invalid.

Confirm the URL is complete and still accessible

Copy the subscription URL again from the account page of your existing provider. Check for missing query parameters, truncation by a messaging app, or spaces at either end. A token in the URL often acts as a credential; don't show it in public screenshots, ticket titles, or web comments. If the URL was reset, the old one may no longer work. Replace it with the current URL from your account rather than repeatedly updating the old entry. Check the field in the app after pasting, and don't submit a URL containing a private token to an online conversion or testing site.

If the request returns an unauthorized or forbidden response, check your account sign-in, access permissions, and whether the subscription was regenerated. If it says the resource wasn't found, confirm that the path is complete. A status code points you in a direction; check your existing provider's documentation for its exact meaning. A temporary redirect may have copied a login page instead of the subscription content. A URL opening in a browser doesn't prove Subscribe can recognize it: browser sessions and app requests may send different state information.

Check the network path if no content is downloaded

If an update keeps waiting or reports a network error, first check whether the subscription domain resolves and which path the current Global Routing setting uses for the request. In some cases, updating requires a working server, but every server in the list is down—creating a loop where you need to update to connect and connect to update. Keep the old list, use a connection you already have and know works, or update on a network that can reach the subscription URL directly. Don't import an unknown configuration to break the loop.

Also check the device time and any HTTPS certificate errors. If updates fail only on public Wi-Fi, turn off the connection, complete the network sign-in, and try again. If the network returns a sign-in page, the app hasn't received subscription content. You can note whether the response is empty, redirects, or contains web page text, but don't publish the full response; it may contain server addresses or credentials. Once the network path is working, try the update again. Repeatedly tapping the button won't fix remote access or content issues and can make the results harder to interpret.

Check the format when content downloads but isn't recognized

An import may be a server subscription, a single share item, or a complete configuration file; these serve different purposes. Use the import method that matches the content and the format provided for Shadowrocket by your service provider. If the response is a login page, account notice, error message, or other text the current import method can't recognize, the import will fail even if the download completes. Don't remove unfamiliar prefixes or change the encoding at random to “fix” the content. That could break valid authentication details and remove the original evidence needed for troubleshooting.

If only some servers appear after an update, first confirm whether the subscription originally included only those entries. Then check for fields or filters that the current configuration doesn't recognize. Identical names don't guarantee identical settings, especially when manual and subscription entries coexist; confirm that the selected item is the one just updated. Before editing a server from a subscription, copy it as a separate test entry. A later update may overwrite manual changes, and a local edit doesn't sync back to the provider.

After a successful update, run Connectivity Test on one server and verify it by opening a web page. If fetching and parsing both work but every server fails to connect, focus on protocol settings or the remote service rather than trying another subscription import method. A one-time client purchase is not a service subscription. The iPhone / iPad version costs $2.99 as a one-time App Store purchase; the Mac / Windows / Android / Linux versions are free. Buying the client doesn't automatically provide subscription content to import.

Latency, initial page load time, and sustained download speed are different measures. Don't judge speed by a single latency value or compare results while changing several variables at once.

Break down what “slow” means

Describe what happens: does the page stay blank after you enter a URL, does text appear while images load slowly, does a download start normally then slow down, or does the connection drop when the screen locks or the network changes? A slow first load may involve DNS, connection setup, or a TLS handshake. Slow sustained transfers are more likely related to bandwidth, packet loss, remote load, or the destination service. If only one app or site is slow, compare it with other destinations first. Don't attribute rate limits, account restrictions, or page resource issues automatically to Shadowrocket.

Keep the device, network, server, Global Routing mode, and test file the same. Pause high-bandwidth tasks on other devices and apps, then repeat the test a few times. To compare direct and proxy paths, choose a destination that works through both; otherwise, the results aren't comparable. Note the approximate time and what happened rather than drawing conclusions from one test. Wi-Fi interference, household network use, and remote server load can all vary over time. The goal is to locate the bottleneck, not to produce one impressive speed result.

Check the local network, route, and destination

Turn off the connection first to check the stability of your local network. Test again where the Wi-Fi signal is strong, away from obstructions, congested channels, or router overload. If the same device is also slow without the proxy, address the local network first. If only the proxy path is slow, compare other servers you already have while keeping the destination unchanged; if several servers are slow on the same site, consider whether the site itself is limiting traffic. Phone heat, Low Power Mode, and heavy background sync can also affect performance, so compare under similar device conditions.

Low latency doesn't necessarily mean high throughput. A short probe exchanges little data and may not reveal congestion or retransmissions during a longer transfer. A more distant server may take longer to complete a handshake but still transfer data well. Don't switch servers repeatedly just to chase the lowest test value; this forces apps to rebuild connections. For video, calls, and downloads, check buffering, continuity, and actual transfer performance separately. A result for one type of activity doesn't necessarily apply to all of them.

Check when the connection drops

If the connection drops only when switching from Wi-Fi to cellular, existing connections may not carry over and new requests may need to reconnect. Wait for the connection to recover, then reopen the destination page. If it never recovers after a switch, note the toggle state, On Demand conditions, and server errors, then check the relevant sections. If drops happen on one particular Wi-Fi network, check whether it requires periodic sign-in, enters a power-saving mode, or limits long-lived connections. A delayed drop by itself doesn't point to a wrong password; authentication errors usually occur during connection setup.

If small requests work but large files or certain pages consistently stall, look into packet loss, transport settings, and possible fragmentation along the route. Don't apply a fixed MTU value found online. Network, protocol, and tunnel overhead vary, and an unsuitable change can disrupt traffic that was working. Only test one setting at a time when you can reproduce the issue, have saved the default, and understand what the setting does. Revert the change if it doesn't help; don't leave an unexplained setting in place.

Use rule logs to explain why some content is slow

In Config mode, a page's main document, images, and API requests may match different policies. Check the domain and route used by the slow request. If only the policy for one rule is slow, first confirm that its assigned server is still available instead of sending every request through Proxy. Repeated failures, retries, and lookups in the connection log often explain perceived delays better than a single speed test. Stop unnecessary stress tests when troubleshooting is done and restore your normal configuration. Running multiple speed tests at once uses bandwidth and skews later results.

DNS troubleshooting isn't just about whether an address is returned. Check who made the query, which resolution path it used, which addresses were returned, and which address the connection selected.

Identify evidence of a DNS failure

If the browser says it can't find the server or the connection log shows a name resolution failure, check the domain spelling, underlying network, and DNS settings in the current configuration. If several unrelated domains fail, start with resolver reachability. If only one domain fails, consider its DNS records, cache, and matching rules. Reaching a server by IP address but not by domain is a clue, not a complete diagnosis: HTTPS services usually need the correct host name and certificate. Entering an IP address directly in a browser may behave differently, so it doesn't prove the server is working or broken.

Check Config for DNS entries, static mappings, or special handling you added for certain domains. Save a copy before comparing it with the original configuration; don't replace settings whose purpose you don't understand all at once. System DNS profiles, router settings, and the app's own resolution path can all be in effect. Check the logs to see which one handled a particular query. Seeing a resolver in system settings doesn't mean all proxy requests use it; likewise, an in-app setting doesn't necessarily cover every request on the device.

Avoid circular dependencies between DNS and connections

A dependency loop can occur if the resolver itself uses a domain name and reaching it depends on a proxy path that hasn't been established yet. First check how the server address is resolved, then how the resolver is reached, and finally the query path for the destination domain. To troubleshoot, return to known-working basic settings rather than layering multiple encrypted DNS options and complex routing. Every resolver has its own connectivity requirements. Adding more addresses doesn't necessarily improve reliability and may make failures appear random.

For encrypted DNS, check that the protocol, address format, port, and certificate name match the configuration requirements, and confirm that the current network can reach the service. Being able to open a regular web page over HTTPS doesn't prove a specific DNS endpoint is reachable. If its requests use a proxy, the assigned policy must already work; if they go direct, test that route. Don't disable certificate checks to work around an incorrect time or name mismatch. Fix the device time and address, then check whether the error persists.

Distinguish address family, rules, and cache

The same domain may return both IPv4 and IPv6 addresses. If the route for one address family is failing, you might see a long initial delay or some requests fail while others work. Check the address selected and the error to determine whether the failure is in resolution or connection. Don't permanently disable IPv6 at the first sign of trouble. The IP-CIDR and IP-CIDR6 rules cover different address families. Rules based on IP addresses may match differently depending on the resolution result, so checking domain rules alone may not explain the full route.

After changing DNS or rules, old cache entries and reused connections may still affect results. Make a new request; if necessary, reconnect the VPN or restart the app under test, then compare the logs. Don't change several settings in a row before the cache has updated. Internal domains on a local network may only be recognized by that network's resolver, so sending them through an external DNS path can break resolution. For home or workplace services, check both DNS and local routing, and confirm the internal address is reachable from the current network.

For a final check, test a regular website, a previously affected domain, and an internal service you need to reach. For each, record whether resolution succeeded, the final policy, and the access result. After confirming the issue is fixed, remove temporary static mappings and rules so they don't break when addresses change. For how DOMAIN-SUFFIX, IP-CIDR, and FINAL work together, see the settings guide. For common error explanations, see Troubleshooting.

Compare screen use, network activity, and connection errors during the same period before assessing battery use. Attribution in the system battery report doesn't necessarily equal all the power the client used.

Choose a comparable observation period

Check the time period in the system battery usage view and distinguish heavy use with the screen on from background activity while idle. Video, downloads, photo sync, and app updates all use network traffic, and VPN-routed activity may affect how the system attributes that use. Don't draw conclusions from a percentage alone: it may show a relative share for the selected period, not the same percentage of the device's total battery drain. Note device temperature, signal strength, and what you were doing to make a useful comparison.

For a fair comparison, keep brightness, network, app use, and duration as similar as possible while observing the connection on and off. Don't compare an idle period with a long video session, and don't keep the screen on or run repeated speed tests just for the test. Weak cellular signal, frequent Wi-Fi drops, and heavy background tasks can all increase power use. If the issue continues with the connection off, broaden your checks to the system and other apps instead of continuing to change rules.

Check repeated failures before simplifying settings

Look for repeated failures to the same domain, servers that keep reconnecting, or subscriptions that keep updating. Frequent retries over a short period can use both network and processing resources. Address the underlying cause first, such as failed server authentication, DNS requests that never complete, or an app repeatedly reaching a blocked address. Hiding log entries won't stop retries. You can temporarily close the app making repeated requests and see whether network activity drops.

Check for unnecessary frequent tests, overly frequent automatic updates, or extra diagnostic logging. Set test intervals and logging options to suit your needs; there is no single best value for every device. When troubleshooting is done, turn off detailed logging enabled for diagnosis to avoid accumulating data and extra processing. Save any necessary information securely, then delete temporary files containing private addresses. If device storage is low, address the storage issue too; don't assume every slow app response is caused by network-related battery use.

Check On Demand against network conditions

On Demand triggers connections based on conditions. Poorly chosen conditions can cause repeated actions when the network changes or conditions alternate. Note each condition's target, order, and action, then temporarily disable automatic triggers and test a similar period using a manual connection. If manual connections are stable but reconnects increase after restoring a condition, check whether it overlaps with another condition or depends on a network state that changes frequently. Don't add and remove several conditions at once, or you won't know which one caused the difference.

If you need a persistent connection, first make sure the selected server is stable on your everyday networks rather than using automatic triggers to compensate for a connection that keeps failing. Pay close attention to returning home, leaving work, and switching from Wi-Fi to cellular. Record whether the toggle stays on after each switch, whether requests recover, and whether retries repeat in a loop. On managed devices or networks, system policies may also disconnect and reconnect VPNs; not every automatic change comes from an in-app setting.

Know when to stop troubleshooting and restore your settings

If pausing requests from an affected app, fixing a server error, or changing one automatic condition restores normal temperature and idle behavior, repeat the test under the same conditions to confirm the improvement. If battery use is still unusually high, restart the device and check for system background tasks. Don't treat brief fluctuations immediately after restarting as a long-term result. Heat while charging may also come from charging and system scheduling, so compare it separately with similar use when the device isn't charging.

When you're done, restore the rules and connection policies you need, and remove temporary full-proxy settings, detailed diagnostics, and frequent tests. Keep a brief summary of the affected period, related requests, changes that helped, and retest results. Without repeatable evidence, don't clear all configurations or reset the entire device; those steps are costly and may erase useful troubleshooting information. If you need more help, use the next section's redacted report checklist instead of sharing a backup that contains a full subscription.

After an update, check which server, Config, and system permissions are still in use. If iPad behaves differently from another device, compare the network and settings instead of assuming devices under the same account have identical states.

Compare before and after an update; don't rush to reinstall

Before making changes, export any server and configuration data you can save. Make sure you can identify what each backup is for, and keep a copy of the current configuration. Backups may contain sensitive information; store them somewhere you control and don't upload them publicly. After updating, check whether the selected server changed, whether Global Routing is set as expected, whether the current Config is still the original file, and whether the system VPN configuration is present. Don't assume an app update and an automatic subscription update are the same event; check them separately even if they happened around the same time.

If the old configuration behaves differently after an update, start with a minimal connection test using a server you already have with known settings. If it works, the basic connection is still possible; restore the original rules, DNS, and automatic triggers one at a time. If the minimal test also fails, return to system permissions, the underlying network, and protocol settings. Don't overwrite several files in a row to test a complex configuration. Keep the original so you can roll back, and note the name of the file currently under test.

Check where you got the app and first-launch approval

Get or update the iPhone / iPad version through the App Store, and verify the developer is Shadow Launch Technology Limited, the official icon, and app ID 932747118. Check the App Store listing for system requirements, and confirm your data is backed up before reinstalling. The iPhone / iPad version costs $2.99 as a one-time App Store purchase; the Mac / Windows / Android / Linux versions are free. For restoring a purchase or account-region issues, see how to restore your download. App access and permissions for an existing subscription are separate.

Installation packages for other platforms are available on the download page through the site's /dl/shadowrocket/ path. On Mac, check About This Mac to identify Apple Silicon or Intel and choose the matching package. If a “developer cannot be verified” message appears on first launch, check Privacy & Security in system settings before selecting “Open Anyway.” If Windows SmartScreen appears, confirm you're using the site's download path, then select “More info” and “Run anyway” as appropriate; follow your organization's policies on managed devices. On Android, allow the browser you're using to install unknown apps when prompted, then revoke that permission afterward. See the installation and approval guide for details.

iPad Checks: Compare Network, Configuration, and Usage

If the same subscription works on iPhone but not iPad, first confirm both devices are actually on the same network—not cellular on one and Wi-Fi on the other. Public Wi-Fi may require each device to sign in separately; signing in on a phone doesn't authenticate a tablet. Compare the selected server, protocol fields, Global Routing, and current Config, and check that one device hasn't kept an old list while the other updated. Devices may sync some data without sharing every local setting and system permission.

An iPad with Wi-Fi only can't be tested over cellular directly. If possible, connect it to another known-working Wi-Fi network or a hotspot from one of your own devices. Keep the server and destination page the same and see whether the issue changes with the network. With Split View, one working app doesn't prove another app is requesting the same domain or using the same connection path; record the actual destination for each. For internal sites or printers, check that the Wi-Fi network allows devices to communicate rather than mistaking client isolation for a rule problem.

If the issue occurs only after locking the screen, leaving the iPad idle for a long time, or waking it, check whether the toggle is still on, whether the network requires sign-in again, and whether On Demand triggered on wake. Send a new request before drawing conclusions; don't rely only on a loading indicator left on an old page. If you need to recreate the VPN configuration, back up your data first and change only entries whose purpose you know. The iPad doesn't need guessed protocol settings of its own; the server should still match the original service details. Look for differences in the device's network and local state.

Prepare a redacted report that others can reproduce

If the issue persists, record the device and system, network type, toggle state, Global Routing mode, action that fails, full error message, and results of comparison tests. “When it started, which destinations are affected, and whether turning off the connection fixes it” is more useful than simply saying it stopped working after an update. Hide subscription tokens, authentication fields, QR codes, and server addresses you don't want to share in screenshots. Don't send a full backup. Once service is restored, follow the quick-start guide to repeat the import, connection, and verification steps, and keep the steps that worked for future reference.