OFFICIAL MANUAL / DIAGNOSTICS

Shadowrocket
Troubleshooting Guide

Find connection, subscription and configuration problems by symptom. Change one variable at a time, keep the original configuration, and retest under the same conditions.

This page is the in-depth troubleshooting section of the manual. For the step-by-step process of importing an existing subscription, choosing Global Routing and connecting, see the setup guide. If setup is complete but something is not working, choose the relevant section below.

01 / CONNECTION SWITCH

Connection switch won't turn on or turns off immediately

A switch that won't stay on is a different issue from a connection that turns on but can't load webpages. For the former, first check whether iOS allows a VPN configuration, whether another connection configuration is in use, and whether the current configuration loads correctly. Repeatedly changing DNS or rules usually won't help identify the cause. Note whether the switch turns off before authorization, immediately after authorization, or a few seconds into the connection; that timing determines what to check next.

Distinguish authorization problems from connection failures

The first time you enable the connection, iOS may ask permission to add a VPN configuration and require device authentication. This is an iOS authorization flow, not subscription authentication. Read which app the prompt refers to, then authorize it only after confirming the source. If you dismissed the prompt, return to Home and try enabling the connection again. If iOS reports a restriction, check your device management policy rather than repeatedly tapping the switch to bypass it.

Turn off the Shadowrocket connection, then open iOS Settings and check whether another VPN configuration is already connected.
Temporarily stop other VPN connections or automatic connection features that you enabled yourself. Return to Shadowrocket and try turning on the connection once.
If it still turns off immediately, confirm that Home has a selected server that actually exists, and check that the current configuration in Config can be read.
Record the system prompt and any in-app error. Then determine whether to address permissions, restore a configuration or check server settings.

Having multiple VPN configurations on a device does not mean they all need to be deleted. The issue to isolate is simultaneous connections or automatic reconnection. Work- or school-managed configurations may be protected by policy, and removing them could disrupt access; check the management requirements first. If one connection stops and another immediately resumes, check the On Demand or automatic connection settings for both before assuming the app's switch is faulty.

Make the smallest change needed to check whether the configuration starts

If the issue began after importing a configuration, keep the original file and switch back to a previously verified configuration. Don't change the server, network and rules or rebuild the VPN all at once; if the issue clears, you won't know which change fixed it. Configuration load errors can come from section headers, misspelled options, policy references or incomplete file contents. Check the reported error location rather than assuming every startup failure means the server is unreachable.

If the switch stays on but there is no traffic, continue to the next section. If it stays on but a server test times out, see the server timeout section. The switch color or system connection indicator shows only one aspect of connection status; it doesn't replace a real request test. Test a specific webpage, check whether a connection is established, then look for the corresponding request in the app. Don't draw conclusions from the icon alone.

If the problem persists after changing the configuration, restart the device normally and reproduce the issue once. A restart can clear temporary runtime state, but it won't fix an incorrect password or server setting. Consider rebuilding your own VPN configuration only after confirming your local information is backed up, you know how to restore your account, and a normal restart and configuration switch have both failed. Resetting network settings has a wider impact and should not be the first step.

What to check after restoring the connection

Once the connection stays on, keep the network unchanged and do three things in a row: open a webpage, return to Home, then lock and unlock the device. Confirm that no new disconnection prompt appears. Then restore only the On Demand conditions you actually need and check whether they trigger repeated connections. If the issue occurs only after locking the screen, note whether the network switched from Wi-Fi to cellular; this is more useful than simply reporting that it disconnects in the background.

02 / TRAFFIC PATH

Connected, but no internet access

An active connection means iOS has established the relevant network processing path. It doesn't mean the server, DNS, rules and destination websites are all working. First determine the scope: do all apps fail, only the browser, or just one domain? Also distinguish pages that won't open at all from pages where text appears but images or sign-in fail. The latter often involves different domains using different policies and doesn't necessarily mean the entire connection is down.

Check the underlying network, then isolate the routing mode

Turn off the Shadowrocket connection and use the same device to open a webpage that normally works. If the underlying network also fails, complete any Wi-Fi sign-in, check cellular data permissions or fix the router connection first. Public Wi-Fi sign-in pages may need to be completed with the connection off. Turn the connection back on only after the underlying network works, so a network without internet access isn't mistaken for a configuration problem.

Once the underlying network works, note the current Global Routing selection. Config mode follows the rules in the current configuration. Proxy mode is useful for temporarily checking whether the selected server can handle requests. Direct mode lets you compare the direct route within the active connection, but does not replace testing the underlying network with the connection off. Restore the original working mode after testing; don't change how all traffic is handled long term just to open one webpage.

Global Routing	Troubleshooting use	What the result does not prove
Config	See which configuration rules and policies are actually matched	One working destination does not prove all rules are correct
Proxy	Temporarily isolate routing rules and test the selected server	A successful request does not prove policy references in Config mode are correct
Direct	Compare the direct route within the active connection	Does not replace checking the underlying network with the connection off

Trace failed requests back to rules and policies

If Proxy works but Config fails, check which rule the domain actually matched and whether its policy points to the expected server. Rules are evaluated in order; a broader rule earlier in the list may catch the request first. Don't check only the rule you expect to match. Use the request record to confirm what actually happened, paying particular attention to DIRECT, REJECT and the final FINAL rule.

This rule snippet illustrates ordering; it is not a complete configuration you can use as-is. example.com is a documentation-only domain, and PROXY must have a valid corresponding policy in your configuration. The first rule matches that domain and its subdomains; the second matches addresses using geographic database data; the last handles requests that matched none of the earlier rules. Design a real configuration for your own needs and verify the policy names it uses.

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

If Proxy fails too, test another server you already have and have previously verified as working. If all servers fail, continue by checking DNS, the current network and shared configuration. If only one fails, see the server timeout section. Don't update every configuration at once: introducing several changes at the same time removes your working baseline and makes troubleshooting harder.

Tell website problems apart from client routing problems

If only one website fails, check whether the problem affects just its sign-in, video or attachment domains. A webpage may request content from several domains, so a working main page doesn't mean every resource domain works. Also check the system time, certificate warnings and the destination service's status. If you see a certificate warning, don't disable verification outright. First determine whether the device time is wrong, a sign-in page is intercepting the connection, or the name specified in the server settings doesn't match.

After making a change, retest the same destination and record the network, mode, server and matched policy. Then test a destination that uses a different policy to make sure the fix hasn't disrupted other traffic. For more on rule matching, see Rule keywords and matching order. Common connection questions are covered in the FAQ.

03 / SERVER REACHABILITY

Server timeouts, authentication failures and dropped connections

A timed-out server test only means the test did not complete within its time limit; it doesn't prove the server is permanently unavailable. The test method, DNS resolution, transport handshake and destination request can all affect the result. Note the test name and exact error, then compare with a real webpage request. If the test fails but browsing works, check the test target and method before deleting a server you already have.

Check the address, port, authentication and transport in order

Open the edit screen for an existing server and compare each field with your original details. Look for spaces, line breaks or full-width punctuation introduced during copying. The address field should contain only the server address required by that field, not a complete share link; the port must match the server. The server name is a local label for identification. Renaming it won't fix the address or authentication details, and the name is not a server-side setting.

Parameter	What to check	Common symptoms
Address and port	Address spelling, port and reachability on the current network	Resolution failure, connection timeout or connection refused
Authentication	Password, UUID, encryption method and server requirements	Failure after handshake, authentication error or connection closed
TLS	Server name, certificate and device time	Certificate verification or handshake failure
Transport settings	Transport type and related settings such as Host and Path	Basic port is reachable, but app requests cannot be established

Fields are not interchangeable across protocols. For Shadowsocks, the password and encryption method must match. For VMess and VLESS, check the corresponding identity details and transport settings. For Trojan, verify the password and TLS settings. Hysteria2 also depends on UDP transport conditions. Two servers having the same address does not mean you can copy all settings from one protocol to another. Use your own server details and don't guess passwords from error messages.

Use controlled comparisons to isolate network and server issues

First test another working server you already have on the current network. Then retry the original server on another available network. The first comparison changes the server while keeping the network constant; the second changes the network while keeping the server constant. If the same server fails on only one network, check that network's access restrictions, sign-in status or UDP conditions. If it fails on different networks while other servers work, the issue is more likely with the server or account.

Don't run several continuous speed tests at once. Repeatedly opening connections in quick succession may trigger server-side concurrency limits and change device load or network congestion. Finish one test before starting another, and keep at least one complete error sample. After switching networks, reconnect so an old connection that hasn't recovered isn't mistaken for the new network's behavior.

Authentication failures usually require checking the original credentials, account status and server-side changes; changing DNS alone won't fix a wrong password. A refused connection is also different from a timeout: the former may mean the target port isn't providing the expected service, while the latter can occur earlier in the route or handshake. Treat log errors as clues and confirm them with a reproducible comparison; don't take one phrase as a definitive diagnosis.

Don't hide the root cause by weakening verification

For certificate problems, first check the device date, server name and original settings. Skipping certificate verification removes an identity check and may leave an incorrect name setting unresolved. If the server uses a special certificate setup, follow the deployment details you have. If you don't have reliable information, keep the current settings and report the error to whoever maintains your existing service. Don't treat a security option as a general-purpose speed switch.

04 / SUBSCRIPTION UPDATE

Subscription import or update failures and unexpected lists

A subscription update involves at least three steps: retrieving the URL's contents, recognizing the format and saving the server list. An import error doesn't necessarily mean the servers themselves are unreachable; a successful update doesn't mean every server in the list works. First identify where it fails: no response, an error page, or content that was retrieved but couldn't be parsed. Each requires a different fix.

First identify what kind of content the link points to

A single share link, a server-list subscription and a full configuration file serve different purposes. A single share link describes one server; a subscription URL retrieves a refreshable list; a configuration file may also include rules, DNS and policies. Don't infer the link's purpose from its appearance; check the information you received with it. Using the wrong import method won't change the content, and repeated attempts may create duplicate entries that are hard to distinguish.

When copying a URL, check for trailing punctuation, line breaks or ellipses added by a messaging app. Some URLs contain query parameters, and losing a single character can cause authentication to fail. Don't change the protocol, path or parameters to something that looks more familiar. A subscription URL may grant access, so treat it as a credential and don't post the full URL publicly when asking for help.

Note the current server group name and approximate list size, and keep any entries that still work before updating.
Confirm that your original subscription URL is complete and that you're using the import method for that type of content.
Update once manually and read the error. Distinguish a network failure from an authentication or format recognition failure.
After a successful update, check the selected server and policy references, then test an actual connection.

Check the network route used for subscription requests

If the update times out or fails during DNS resolution, first check whether the underlying network works. Then determine whether the subscription request depends on the current connection, which may no longer work. A URL may behave differently over a direct route and an existing connection; confirm with one controlled switch rather than repeatedly tapping Update. If you need an existing working connection to retrieve the subscription, use a server you've already verified to complete the update and avoid a dependency loop.

If the response is a sign-in page, verification page or access error, the app can't parse it as a server list. A page opening in a browser proves only that content was received, not that it is a valid subscription. Don't save the page as text and force it into the app as a configuration. Check your account status, URL and original details; if needed, ask the provider of your existing service what type of content the URL returns.

If the list is empty or changes substantially after an update, stop updating repeatedly. Check whether you imported a different URL, the original subscription was revoked, or the server changed the returned list. If you kept the previous list, compare group and server names, but don't assume matching names mean identical connection settings. Entries with the same name may have different addresses or authentication details; verify with an actual connection test.

Handle duplicate entries and stale references

Manually added servers and subscription-generated servers may appear together. Before cleaning up, check where each came from so you don't delete a manual entry you still need. If a rule policy referred directly to a server name, a rename after a subscription update may break that reference. Check which server the policy actually points to rather than assuming it's fine because the list still contains many entries. Fix broken references before removing duplicates.

The client list, subscription account status and configuration rules are separate layers. Updating a server list usually doesn't update all rules and should not be expected to fix DNS settings you changed manually. After recovery, check the update time or result, list contents, current selection and an actual request. For more on the different content types, see Share links vs. subscriptions.

05 / PERFORMANCE

Normal latency but slow speeds or choppy video

Latency, throughput and webpage load time measure different things. A latency test mainly reflects the time for one specific interaction; it can't be directly converted into sustained download speed. Video playback also depends on the destination service, caching, bitrate and segmented requests. Make “slow” observable: for example, the first load takes a long time, playback starts quickly then stalls, or only large files transfer slowly. Then choose a test that matches the symptom.

Set up a repeatable comparison

Keep the network, device, destination and server the same. Stop other high-bandwidth tasks and repeat the test once. If you change the test site and server at the same time, the results won't be comparable. Browser cache can also speed up a second visit, so note whether it was the first or a repeat load. For video, note whether it stutters only after seeking. The destination's own load can change too, so don't judge the whole route from one result.

Compare speed with the connection off, then turn it on and confirm the destination uses the expected policy. If the underlying network is already slow, check Wi-Fi signal, router load and cellular coverage first. Being connected to Wi-Fi doesn't guarantee a strong signal or good upstream bandwidth. Distance from the router, frequent access point changes and other devices sharing the network can make a connection test pass occasionally while sustained transfers remain unstable.

Pause background backups, app updates and other transfers, and note whether the device is getting warm.
Compare the same destination with the underlying network and the connection enabled; confirm Global Routing and the matched policy.
Switch only to another working server you already have, keep everything else the same and repeat the request.
Change networks last, and compare whether the issue follows the server, destination or network.

Distinguish DNS delays, handshake delays and slow transfers

A long blank screen followed by content appearing quickly may point to DNS or connection handshake delays. A page that loads gradually is more consistent with throughput, retransmissions or resource requests. Check request records for failing domains, connection establishment and errors instead of changing every setting based on how it feels. If the main page works but images load slowly, check whether image domains use a different policy; investigate the rules rather than testing overall speed.

Server location, current load, connection quality to the destination and route congestion all affect performance. A low-latency server isn't necessarily faster for a particular destination, and the same server may perform differently across websites. Compare only with servers you already have; there's no need to add a service for troubleshooting. Judge a route's suitability only after getting consistent results under the same conditions several times.

Check apps and protocols that use UDP separately. Some networks handle UDP differently from ordinary webpage connections, so being able to browse doesn't prove that real-time audio, video or other UDP-based traffic works. Don't change the transport protocol, port and advanced settings all at once. First check what the server supports, then test one change at a time and record the result. Entering a higher bandwidth value won't improve the actual upstream capacity and may make congestion more noticeable.

Keep advanced changes limited

Network settings such as MTU are not general-purpose speed boosts. If only larger requests stall while smaller ones repeatedly succeed, first record the exact steps to reproduce the issue and compare networks. Then adjust a setting only if the environment's requirements are known. Note the original value before each change and repeat the same failing request afterward; restore it if there's no improvement. Without a clear symptom, defaults are usually easier to maintain than several unverified settings.

An overheated or low-battery device, or continuous screen recording, can also affect the experience. Let the device return to a normal temperature before a short comparison. Don't saturate the network to diagnose routine browsing issues. Success means the task that originally failed now completes reliably, not that a single test number looks better. If the main symptom is slow initial resolution, see the DNS section. If it comes with persistent heat, see the battery section.

06 / NAME RESOLUTION

DNS resolution failures and domains that won't load

DNS translates domain names into addresses used to establish connections. A server latency test can succeed while a webpage fails because the test and page may use different domains, resolution paths or rules. First determine whether the failure occurs during resolution or after an address is returned. Both can look like a browser that keeps waiting, but they call for different fixes. In-app errors and request records are more useful than a blank page alone.

Start with one specific domain

Choose a domain that fails repeatedly and note the time and current network. Compare it with a domain that usually works to see whether all DNS lookups are failing. If every domain fails, check whether the DNS address in the configuration is correct and whether the resolver is reachable over the expected route. If only certain domains fail, consider their DNS records, caching, routing rules or address-family differences; don't replace the entire DNS setup straight away.

A configuration may use system resolution, a specified resolver and different request routes. Check the Config that is actually active; you may be editing a file that isn't enabled. If the server address is itself a domain name, it also needs to be resolved first. A dependency loop can occur if resolving it relies on a server connection that hasn't been established yet. Record server-domain resolution separately from destination-domain resolution.

Use rules to understand how DNS and connections interact

Domain rules and address rules match different things. DOMAIN matches a specific domain; DOMAIN-SUFFIX matches a suffix and its subdomains. IP-CIDR matches an address range, while GEOIP relies on address and database information. To determine which policy a request uses, check the actual match. A domain appearing in the configuration doesn't mean it takes precedence over earlier rules.

[Rule]
DOMAIN,example.com,PROXY
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
FINAL,PROXY

This snippet illustrates match targets only. The example network range is reserved for documentation, not a usable service. no-resolve means the address rule won't actively trigger domain resolution for matching; it does not disable all DNS. Adding this parameter broadly without understanding the distinction may stop checks that depend on resolution from behaving as expected. Design complete rules around your existing policies and actual destinations.

Keep a copy of the original configuration before changing DNS. Change one resolver or related option, reconnect and repeat the same request. Browsers, apps, the system and the connection may each cache results, so seeing an old result briefly doesn't necessarily mean the new setting failed. But don't repeatedly clear everything. Close and reopen the destination app first; if needed, restart the device normally, then compare the recorded resolution and connection results.

Distinguish address-family, encrypted DNS and destination issues

When both IPv4 and IPv6 records exist, reachability may differ across networks. If delays occur only on a particular network, check which address was ultimately used and the connection error rather than assuming the domain doesn't exist. Accessing a webpage by IP is not a reliable substitute: websites may depend on the hostname, certificate name and virtual host. An IP address failing on its own does not prove the domain's DNS is wrong.

Encrypted DNS still needs a reachable connection path and may depend on certificates and system time. Encryption doesn't guarantee successful resolution on every network. If all domains fail after a change, restore the last known working settings first, then check whether the resolver is unreachable or the route depends on another connection. Don't disable certificate verification to hide an identity check problem in the DNS connection.

If the same domain also fails to resolve on other working networks, the problem may be with the domain itself. If it resolves but the connection fails, return to the server and rules sections. After a fix, check a domain that failed, a working comparison domain and the current server's domain to make sure all stages work. For more symptom comparisons, see DNS resolution troubleshooting notes.

07 / BATTERY AND ACTIVITY

Excessive battery drain, heat and repeated background connections

Battery percentages in system statistics depend on the time period and the device's overall usage. An app's share may rise because other apps were used less, or because of traffic processed by the connection, repeated retries or foreground diagnostics. One percentage alone doesn't prove abnormal power use. First record charging status, screen use, network type and actual device temperature, then compare similar conditions.

Separate idle drain from transfer-related battery use

File downloads, HD video, cloud sync and hotspot sharing all create sustained network activity. Processing this traffic through a connection may increase the device's workload, but the app generating the requests may not be Shadowrocket. Pause high-bandwidth tasks you know about, keep other usage consistent and check whether the device still heats up while idle. Don't judge everyday standby battery life while running intensive tests.

In Settings, choose the battery usage period that matches the issue and check background and foreground activity, including whether other apps were active at the same time. Note if the device was charging, had just completed a system update or was processing photos. These conditions affect heat and battery use; mixing them makes it impossible to isolate the cause. Record specifics such as “same network, screen off, sync paused, but connections still repeat” rather than just “battery seems worse.”

Check On Demand and network changes

On Demand starts a connection when its conditions are met; it doesn't have to be enabled for troubleshooting. If the connection turns itself back on after you disable it, check your On Demand conditions and any other automatic connection settings in iOS. Temporarily stop the relevant automatic behavior and test a manual connection. Once it's stable, restore settings one at a time so multiple conditions don't trigger repeated starts and stops.

Weak Wi-Fi, repeatedly moving in and out of range, and changing cellular signal can all trigger reconnections. Repeated retries consume resources and may briefly interrupt webpages. Test with the device in a location with a stable signal, then compare with what happens while moving. If the issue occurs only during network changes, record the networks before and after the switch rather than attributing all background activity to the app.

Record the battery statistics period, current network and device temperature; stop active speed tests.
Pause known high-bandwidth tasks and check whether requests continue while the device is idle.
Temporarily disable On Demand and test a manual connection to see whether connections still repeat.
Switch only to another stable server you already have and see whether retries and heat decrease together.
Restore necessary features and check again, keeping the smallest set of conditions that reproduces the issue.

Reduce unnecessary diagnostic activity

Keeping detailed diagnostics on for a long time, running Connectivity Test continuously or repeatedly updating every subscription adds network and processing load. Enable only the diagnostics you need, briefly capture a useful failure sample, then turn them off. Don't leave diagnostic tasks running in the background as a connection status indicator. After restoring normal settings, check that no automation is still triggering repeated tests or requests.

Repeated handshake failures from one server may use more resources than a stable connection. First fix the address, authentication or network conditions as described in the server timeout section rather than merely reducing logging. If one destination app keeps making failed requests, check its rules and DNS too. A bad policy can cause repeated requests and higher battery use even though the underlying cause lies in that destination's connection route.

If the device is noticeably hot, stop high-load tasks and let it cool in a normally ventilated place before doing a short test. Don't repeat measurements for a long time at abnormal temperatures; device performance and network behavior may already have changed. Don't extrapolate a brief battery drop to a full day. Compare records from similar periods with similar networks and usage for meaningful results.

08 / RECOVERY AND IPAD

Post-update issues and iPad recovery

After an issue appears following an update, first identify what actually changed. An app update, system update, subscription refresh and configuration switch may happen around the same time; don't assume the app update caused the problem. Note the last working setup and what's different now, then use the earlier sections to diagnose the symptom. Prices, system requirements and device compatibility are as listed on the App Store page. Get and update the app through the App Store; see the purchase guide to verify your copy.

Back up first, then restore in order of impact

Keep a copy of your current configuration, details for servers you added yourself and any subscription URLs you need. Store the backup somewhere you control. Don't share files containing passwords or subscription parameters publicly. Restart the device normally and reproduce the issue on the original network with the original destination. If it works again, check whether the cause was temporary runtime state. If it still fails, check the underlying network, connection switch, server, rules and DNS separately; don't erase everything at once.

If the problem began immediately after editing a configuration, restore a previously working copy first. If it began after a subscription update, check server changes and policy references. If VPN authorization became abnormal only after a system update, check your VPN configuration in Settings. Work back through known changes one at a time; don't treat reinstalling, deleting configurations and resetting network settings as a single troubleshooting sequence.

Before downloading the app again, check which Apple Account you used to purchase it and confirm the purchase in your history. A purchase record isn't a backup of your server details, and downloading again won't fix an expired subscription. For restore options and important notes, see Restore purchases on a new device or after reinstalling, or read How to restore a purchase with your original account. Don't sign out of your account just to troubleshoot a connection; that adds another variable.

On iPad, distinguish purchase, configuration and connection status

On iPad, check separately whether the app is available to download, whether your own configuration has been imported and whether the connection is actually on. These are not interchangeable. Availability to download with the same purchase account and the scope of a universal purchase are as listed on the App Store page. Even after downloading the app, you still need to check your subscription, server and rules. Don't assume this device has the same settings just because another one works.

Landscape, portrait and Split View may move controls on screen, but they don't change the troubleshooting order. Before editing, check the selected server group and Config to avoid changing a different item in a split view. If an option looks unexpected after switching windows, return to Home and check the current selection before testing a real request. Don't infer the active state from the window position or the page you last viewed.

An iPad with Wi-Fi only has different network comparison options from a device that also has cellular connectivity. If you can't switch to a cellular network, test on another working Wi-Fi network you're authorized to use. If the same configuration behaves differently on two devices, compare their networks, system authorization, Global Routing, selected server and actual configuration contents. Comparing server names alone can miss differences in settings.

Troubleshoot lock-screen, network-switching and single-app issues

If access takes longer to recover after locking an iPad, first check whether Wi-Fi reconnected, then whether the VPN connection was re-established. Don't rely solely on the status bar; what it shows varies by display context. Reproduce the issue with a specific webpage after unlocking and note whether the first request fails and then recovers by itself. If it happens on only one network, check that network's stability and sign-in requirements first.

An external keyboard, multiple browser windows or webpages in different apps may involve separate caches and sessions. If only one window has a problem, close it and reopen the page to check for a sign-in or cache issue. If other apps work, there's no need to rebuild the device's entire network configuration. If every app fails, return to checking the underlying network and global routing, working from the specific issue outward.