Shadowrocket
Complete Troubleshooting Guide

Connection switch won’t turn on or connection stops immediately

First, distinguish between two symptoms: tapping the connection switch on Home never starts a connection, or the connection starts and then stops after a few seconds. For the first, check system permissions, device restrictions, and whether the configuration is valid. For the second, also check other VPN configurations, On Demand conditions, and network changes. Note the exact message after tapping, whether the system shows a confirmation prompt, and when the switch resets. “Won’t turn on” alone doesn’t point to a server problem. If the system hasn’t established a local VPN session, repeatedly switching servers usually won’t help.

Check system permissions and device restrictions

The first time you connect, the system may ask to allow a VPN configuration and confirm with your device passcode or system authentication. Continue only if you’ve confirmed the prompt comes from the Shadowrocket app you just opened. If you tapped Cancel, return to the app and try connecting again to see whether the permission prompt reappears. In system Settings, find VPN management and check whether the configuration is listed; the menu name and location may vary, so try searching Settings. A listed configuration means the system saved a connection profile—it doesn’t mean the server connection succeeded.

If your device is managed by your employer or school, management policies may restrict VPN changes. Check for a management notice and ask your device administrator what’s allowed; don’t remove management settings you don’t recognize. On a personal device, check whether another VPN service is connected. Disconnect it in its own settings, then test Shadowrocket. Record the original state so you don’t accidentally remove a configuration used for work. If the switch in system Settings also resets immediately, keep the system message and investigate permissions before changing routing rules.

Use minimal changes to distinguish configuration issues from automatic connections

Temporarily turn off On Demand and note its previous conditions. It may reconnect after a network change, making it seem as if the switch failed to stay off. Then confirm Home has a server selected with complete settings, and check in Config that the active configuration loads properly. If the issue started right after editing the configuration, copy the file first, then restore the latest known-good copy. Don’t overwrite your only copy with a large, unverified configuration. Restore rules, DNS, and rewrite settings separately to identify which part affects the connection.

Exit the current workflow, reopen the app, and try once more. If it still fails, save your work and restart the device to rule out a temporary system network-extension issue. A restart won’t fix a server. If it only helps briefly, look for a trigger such as switching from Wi-Fi to cellular, waking the device after locking it, or another VPN service connecting. Test each condition separately and record when and how the issue occurs, rather than treating different problems as one.

Confirm the fix is stable

Once the switch stays on, visit a website that normally works, then lock and unlock the device and visit it again. Checking only the switch’s color can miss a session that’s connected but can’t carry traffic. If the switch stays on but websites won’t load, continue to the next section. If a system permission error returns, save the message and check device permissions. To get the app again, follow the restore purchased app guide. App updates and restores are handled through the App Store; check the App Store page for system requirements.

When describing the issue, specify whether it “stops immediately after a manual connection” or “stops after a network change,” and include a summary of the system message. The configuration name, network type, and whether On Demand is enabled can help reproduce it. Don’t include server passwords, subscription URLs, or credentials in public screenshots. This record is also your baseline: to verify the fix, repeat the same action on the same network.

Connected, but websites or apps can’t access the internet

The connection indicator means the system VPN session is established; it doesn’t guarantee every request can reach its destination. A request may involve DNS, rule matching, a server connection, and a response from the destination site. First disconnect Shadowrocket and test the same website. If it still fails, check Wi-Fi sign-in, cellular data permissions, the router, and the destination site. Public Wi-Fi may require you to complete a system sign-in page first. If the underlying network has no internet, changing PROXY or DIRECT rules only adds variables.

Use Global Routing to narrow down the issue

Note your original Global Routing setting, then run brief comparisons. Config uses the rules in the active configuration to handle requests. Proxy generally sends regular traffic through the selected proxy route. Direct lets you compare against the underlying network. These are troubleshooting modes, not three separate servers. System traffic, special handling in the configuration, and specific app behavior may still affect the results, so don’t use one comparison to infer the route for every request. After each change, make a new request rather than checking a cached page.

If Proxy works but Config doesn’t, open the configuration that’s actually enabled and check which rule matches the destination domain first. Common causes include a broad rule placed before a specific one, a policy pointing to a name that no longer exists, or a REJECT rule blocking resources the app needs. Don’t check only the homepage domain: opening an app can also request domains for authentication, images, and APIs. Use request logs to identify the specific failure. This is more useful than permanently routing all traffic through Proxy.

Read rules in order; don’t just search for a keyword

This snippet illustrates rule-matching order; it is not a complete configuration you can use as-is. Rules are generally checked from top to bottom, and the first match determines how a request is handled. FINAL handles requests that didn’t match earlier rules. The private network ranges in this example are only there to illustrate direct access to a local network; check your own network and configuration requirements. IP-based rules are related to DNS resolution and shouldn’t be treated as completely independent settings.

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

If Config and Proxy both fail but Direct works, check the selected server and proxy route first. If only one website fails, check whether the destination service is having an issue, DNS is returning an unsuitable address, a rule is matching incorrectly, or the server is denying access. A website working in a browser doesn’t guarantee other apps will work; they may use different domains, connection methods, and caches. Compare two unrelated websites and a commonly used app to avoid mistaking a single-service issue for a general loss of internet access.

Restore the original configuration and verify real requests

When you’re done troubleshooting, restore your original Global Routing setting and keep only rule changes you’ve confirmed are necessary. Reconnect and make a new request. Confirm the page and its resources load, then retry the specific action that failed, such as signing in or uploading an image. If it still fails, record the domain, matching rule, policy, and error type, then check the routing rules guide. Don’t add a large number of exceptions at once. Limit temporary direct access to confirmed destinations so you don’t change how other requests are handled.

If the domain won’t load but a test still returns a result, stop changing routing modes and continue to DNS issues. A connection test and an actual website visit cover different parts of the route. A successful test only confirms the part it actually tested.

Server timeout, connection refused, or protocol handshake failure

Keep a record of the error type first, then check the server settings. A timeout means the expected response didn’t arrive within the test’s wait period; the failure could be at the underlying network, server port, protocol handshake, or destination request stage. A connection refused error more often means the destination port rejected the connection. For authentication failures, check the credentials first. Results from different test methods aren’t directly comparable. Record the Connectivity Test result together with the test method; a single number doesn’t prove every protocol function is working.

Rule out the wrong entry and an incorrect address first

On Home, check which server is selected, not just the editor page you opened most recently. A subscription update can add entries with similar names while leaving old ones in the list. Open the selected entry and compare the protocol, server domain, and port field by field. Look for spaces or full-width characters introduced when copying, or a full share link pasted into the server address field. The domain and port serve different purposes and normally belong in separate fields. Don’t assume the address from a region or note in the entry name.

If the same entry times out on Wi-Fi but works on cellular, the issue is related to the access network or the route to the server; that doesn’t prove the server is fully operational. First confirm that both networks can reach ordinary websites, then compare again at about the same time to avoid differences in server load. If all existing entries fail on one network but work on another, check router restrictions, network sign-in, and UDP availability. Don’t change every entry’s password and hope for the best.

Check protocol-specific handshake settings

For TLS configurations, check the domain-related fields provided by the server, the device’s date and time, and certificate validity. An incorrect device clock can affect certificate checks, so correct it before testing. Don’t routinely disable certificate verification; that changes the connection’s identity checks. In protocols with transport settings, Host, Path, and TLS-related names may serve different layers. Don’t substitute one for another just because the values look similar. See the protocols and configuration fields guide for details.

After importing a share link, check that the parsed result is complete. If the original information is missing transport settings, a successful import doesn’t prove the configuration will work. Ask the original provider to confirm the details rather than guessing based on another entry. Before editing an entry generated by a subscription, make a copy; a later update may overwrite your changes and bring the issue back. Record why you changed a setting—for example, “corrected Path after checking the server documentation”—rather than just “changed a parameter.”

Verify with real-world access; don’t hammer the test

Select an entry whose settings you’ve checked, run one test, then visit the website you actually need. If it still fails, save a summary of the error and network conditions, then test again later. Repeated batch tests can add unnecessary request load and make intermittent issues harder to spot. If one server entry keeps failing, give your service provider the error type, time, and comparisons you’ve already tried. Remove identity fields, keys, and full subscription URLs before sharing. Troubleshooting needs the symptoms and types of settings—not public credentials.

If the handshake succeeds but larger pages or uploads fail, continue to the speed section to check sustained transfers, packet loss, and MTU-related issues. Don’t label every problem a server timeout. Identifying where the failure occurs helps you choose the right fix.

Subscription update failed, imported list is empty, or duplicate entries

Subscription handling involves several stages: obtaining the URL, requesting the server, receiving the response, parsing the format, and adding entries to the local list. An update failure doesn’t necessarily mean existing entries have stopped working; only the update request may have failed. Note the existing entry count and names, save a recoverable copy, then try one update and read the message. Get subscriptions from your service provider. Don’t replace the original with an URL from an unknown source or post a full authentication URL in a public discussion.

Check that the imported content matches the import method

A single-server share link, a subscription that provides a server list, and a full configuration file are different types of content. A share link describes one entry, a server-list subscription supplies a group of entries over time, and a configuration file may also include rules and DNS settings. Using a webpage or configuration URL with the wrong import method can result in a successful request but no recognizable entries. Check the original provider’s format and import instructions, then follow the Getting Started guide. For help identifying link formats, see share links vs. subscription URLs.

When copying the URL, check that you copied the address rather than only its visible title, included any parameters after the question mark, and didn’t pick up a line break from a messaging app. Don’t alter capitalization or encoded characters, and don’t replace standard punctuation with full-width characters. If you need a new link, get it from your original service provider and confirm its purpose. Subscription URLs often contain access credentials; they may also be saved in the clipboard, screenshots, and browsing history. After troubleshooting, clean up copies you no longer need instead of passing the URL between apps.

Distinguish network errors, response errors, and parsing errors

For a request timeout, first check whether the current network can resolve and reach the subscription domain. For a certificate error, check the device’s date and time, the domain, and the certificate. A clear HTTP status means the request reached a particular stage. A 401 or 403 is often related to identity, permissions, or access restrictions, but the server can confirm the specific cause. A 404 may mean the path changed or the URL is incomplete. A 429 indicates a rate limit: stop refreshing repeatedly and wait as instructed by the response. Don’t obscure the first useful error by tapping again and again.

If the response is a sign-in page, information page, or network sign-in page, the client may have received HTML instead of subscription data. That’s why opening a URL in a browser doesn’t mean it can be parsed as a subscription. If your provider offers a way to inspect protected content, follow its instructions to check the response type. Don’t share subscription credentials with an unfamiliar online conversion service. Some subscriptions also offer client-specific output formats; check that Shadowrocket is selected rather than relying on the URL suffix.

Handle duplicate entries and changes after an update

When entries are duplicated, first distinguish between adding the same subscription more than once and names that are duplicated in the server-provided list. For the first case, keep one source after confirming its backup and ownership. For the second, compare address, port, and protocol; don’t delete entries based on names alone. An update may also remove old entries or change their names, which can alter the current selection. After updating, return to Home and confirm the selected entry still exists and has complete settings, then test real access. A new name in the list alone doesn’t prove the update worked correctly.

If you’ve manually adjusted individual local entries, copy them as separate entries and label their purpose before updating. Keeping subscription-generated content separate from personal changes helps avoid recurring problems caused by overwritten edits. If only the update request failed but existing entries still work, keep the working setup for now, note the error and response time, and check with your service provider. To verify the fix, confirm that the update completes, entries are recognized, the right one is selected, and real traffic works—not just that the error message disappears.

Connected, but speeds are slow or traffic is unstable

Describe “slow” as a repeatable symptom: does the first page take a long time to open, does loading stay slow after it starts, does video keep buffering, or does a large upload stall? A long initial wait may involve DNS resolution and the handshake. Sustained transfers also depend on the access network, server load, destination service, packet loss, and transport method. Low latency doesn’t mean high throughput, and a brief connection test can’t predict a long transfer. Don’t assume one server will be faster for every task based only on its ranking in a single Connectivity Test.

Compare under the same conditions

Choose a legitimate test item with relatively stable content and size. Compare it on the same device, access network, and around the same time. Pause other high-traffic tasks, check the Wi-Fi signal and cellular data, then test the underlying network and current proxy route separately. Record the initial wait, sustained loading, and any interruptions rather than a single average number. Tests use data and may affect server load, so run only enough to reproduce the issue; don’t keep multiple tests running in parallel.

If every website is slow, start with the access network and selected server. If only one service is slow, check its resource domains, routing paths, and server response. Some pages load text quickly but images or video slowly because different resources may use different domains and routes. Use request logs to find the slow part, then check the rules in Config. Replacing the entire configuration with another complex file changes DNS, rules, and other handling at once, making comparisons less useful.

Check handshakes, repeated connections, and transport limits

Repeated disconnects and reconnects can trigger repeated TLS or other protocol handshakes, making short requests feel especially slow. Check whether slowness coincides with timeouts, closed connections, or network changes. If it only happens in elevators, while moving, or on weak Wi-Fi, improve the access conditions first. If a stable network resolves it, rules probably aren’t the first thing to change. For UDP-based transport, check that the current network supports the required traffic. Loading ordinary webpages doesn’t prove the UDP route is reliable.

If small pages work but larger transfers stall, packet loss, path MTU, or server limits may be involved, but the symptom alone can’t confirm the cause. Don’t enter different MTU values in multiple places. Change one setting in a copy only if the current protocol provides it and you have server documentation or reproducible evidence. For configurations such as WireGuard, also check the allowed address ranges and actual routes. Record the original settings so you can restore them and don’t leave temporary test values in place.

Rule out delays caused by configuration processing

Complex rules, remote resources, or request rewrites may add processing steps, but that doesn’t mean every feature is faulty. First copy the current configuration. In the copy, disable only the most recently added group of settings and test the same task. If it improves, narrow down the cause one change at a time. Settings involving HTTPS inspection or rewriting change how traffic is handled; understand their purpose and certificate implications before using them. Don’t expand their scope just to try to improve speed. See the configuration file sections guide for an overview.

Also check whether rules send a service that needs local network access through a proxy, or send resources that depend on a particular route directly. Don’t use local printing or file access to diagnose ordinary websites, or vice versa. After fixing a rule for a confirmed destination, verify the result using your original Global Routing setting. Staying on Proxy may bypass a rules issue without actually fixing the configuration. A configuration copy helps isolate variables; it’s not a reason to keep multiple unorganized files with unclear purposes.

Verify the result with a real task, such as loading a page, playing a video continuously, or completing an upload. Check whether the same stall still occurs. If speed drops only at certain times, record the time, access network, and error summary, then check with your service provider. Don’t treat one unusually fast result as a confirmed fix, or blame app settings for a speed limit imposed by the destination site.

DNS resolution failures and individual domains that won’t load

DNS translates domain names into addresses that can be reached. Server connections, rule matching, and accessing a destination may all depend on it. Common symptoms include a server domain that won’t resolve, a website reporting that its address can’t be found, missing resources, or a Connectivity Test that returns a result while the actual website won’t load. First identify whether the failed domain belongs to the server or the destination website; these fail at different stages. A server-domain issue may prevent the proxy connection from being established, while a destination-domain issue can occur after the session is up. Don’t assume one setting will fix both.

Check which DNS source is currently active

In Config, confirm which file is in use, then check its [General] section and related DNS settings. System DNS, DNS settings in the configuration, and encrypted DNS may all affect different requests. Seeing system on one line doesn’t prove all lookups use the same path. Record the original values, read the setting’s description in the current app, and compare one change at a time. The snippet below only shows key-value syntax. It isn’t a recommended configuration for every network and shouldn’t replace your full file.

[General]
bypass-system = true
dns-server = system
ipv6 = false

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

If the issue started after changing DNS, restore the previously working setting in a copy of the configuration, reconnect, and make a new request. Browsers, the system, and apps may all cache results, so an old page that still fails or an existing connection that still works doesn’t necessarily mean the change had no effect. Close existing requests and try again; if needed, restart the affected app. Clearing all device settings isn’t a routine way to clear a cache. Change only the DNS source or one related option at a time, and keep a way to revert.

Distinguish timeouts, missing records, and address reachability

A DNS timeout means no response arrived in time; check the path to the DNS service. An explicit no-record result calls for checking the domain spelling, record type, and destination service. If DNS returns an address but connecting to it times out, the issue may be with routing or the destination service; switching DNS providers again may not help. With encrypted DNS, also consider how its server address is resolved and reached, and whether it depends on a proxy route that hasn’t been established yet. Avoid creating a startup dependency loop.

If the problem occurs only when IPv6 is enabled, check whether the current network has a working IPv6 route and whether the returned address matches the actual route. You can disable IPv6 in a copy for a comparison, but that doesn’t mean it should be off on every network. Test the actual service after restoring the setting. If the network depends on a particular address-translation mechanism, opening a numeric address or testing only one address family can be misleading. “One address family fails on this network” is more precise than “DNS is bad.”

Check how local mappings interact with rules

A local mapping in [Host] can override normal resolution. If the mapped address is outdated, only the affected domain may stop loading. Search the configuration for mappings and related rules for that domain, and check that they aren’t leftovers from an old test. Save a copy and note the purpose before deleting anything. Domain and IP rules also have an order: some IP-based checks require DNS to return an address first. If an earlier rule matches the domain, a later GEOIP or IP-CIDR rule won’t continue as an ordinary subsequent match for that same request.

Don’t permanently add an address returned by a website to [Host]. Services using content delivery or dynamic addresses may return different results depending on network and time; pinning an address can disrupt routing or cause certificate, resource, or reachability issues. Opening an HTTPS website by IP address also isn’t a reliable equivalent test because the certificate name and server’s virtual host may still depend on the domain. Be clear about whether your test checks DNS resolution, a port connection, or a complete request.

After the fix, test the server domain, the website that failed, and its resources separately, then return to your usual Global Routing mode in Config. If the issue occurs on only one Wi-Fi network, check the router’s DNS and network sign-in as well. For more examples, see troubleshooting DNS resolution failures. Keep records to domain category, resolution error, and matching policy; don’t share sensitive parameters from full request URLs.

Increased battery use, heat, or unexpected background activity

High activity for Shadowrocket on the system battery screen doesn’t necessarily mean a particular app feature is responsible for all the power use. A VPN carries network traffic for other apps, and system statistics are also affected by foreground use, background communication, and connection time. Compare the same device during similar periods and tasks. Note screen use, access network, charging status, and current transfers. Comparing battery use while streaming video with battery use while the device is idle won’t identify the source of the extra drain.

Set up a comparable observation period

When the device’s charge and temperature are relatively stable, observe a normal period of use, then review the system’s battery and data statistics. There’s no need to target a fixed battery-use percentage; focus on noticeable differences between similar tasks. Pause known high-traffic activities such as large file syncs, extended video, or Personal Hotspot use, and check that system updates or photo processing aren’t happening at the same time. Keep the network consistent where possible. Weak cellular signal and the resulting wireless activity may be more important to check than rule processing.

If the connection switch keeps changing or request logs show repeated failures and retries, fix the connection issue first. Reconnecting, resolving names again, and repeating handshakes all increase activity and may keep the app busy in the background. Check whether multiple automatic connection conditions conflict, whether On Demand repeatedly triggers after a network change, and whether the device is at the edge of unstable Wi-Fi coverage. If you turn off automatic connections for a brief comparison, record the original settings and restore them after troubleshooting if needed.

Check diagnostic tasks and ongoing network requests

Batch Connectivity Tests, frequent subscription updates, detailed request logs, and prolonged debugging all create extra work. When you’re done troubleshooting, stop tests you no longer need and restore your usual logging level, then check whether system activity settles down. Don’t run multiple test groups at once to measure battery use; the troubleshooting itself may be the load. Keep logs only as long as needed. Longer logs may contain visited domains and request details, so check for sensitive information before exporting or sharing them.

If the device continues to use data while idle, first check whether another app is syncing in the background. Where system settings allow, pause related background tasks one at a time and compare data use; don’t disable every app permission without checking. If continuous retries start only when one app opens, check its failing resources and routing path, then use the no-internet and DNS sections to investigate. Fixing the failed requests addresses the cause more directly than simply limiting background activity; otherwise, the app may keep retrying.

Use a configuration copy to isolate additional processing

If the issue began right after adding configuration content, copy the current file and revert only the most recent group of changes in the copy, such as a new rewrite or more complex request handling. Keep the same server, Global Routing mode, and task while comparing heat and activity. If you also change servers, DNS, and the configuration, you won’t know what made a difference. Complexity isn’t determined by line count alone. Check which settings actually match current traffic and whether they trigger extra requests or repeated failures.

Don’t assume a particular protocol will always use more or less battery based on its name. Access network quality, retransmissions, connection count, and task type all affect the result. To compare different entries you already have, test them one at a time with the same task and confirm each can complete requests reliably. A failing connection compared with a working one primarily shows a difference in availability, not a fixed difference in power use between protocols.

For the final check, return to your normal usage conditions. Confirm that the unusual background activity no longer occurs and that networking still works after you stop temporary logging. When contacting support, include the system battery screen’s time range, main tasks, charging status, network type, and any reconnection behavior. A percentage screenshot alone isn’t enough; without usage conditions, statistics can’t reliably distinguish app processing from other app traffic or wireless network activity.

Troubleshooting after an update and iPad-specific checks

Finding an issue after an update means it occurred around the same time as the update; it doesn’t prove the update was the only cause. The app, system, subscription content, and access network may all have changed around then. First record what actually changed: whether the app was updated, the system restarted, the subscription refreshed automatically, or the configuration was replaced. Then repeat the same failing action. Check the App Store page for update information and system requirements; don’t guess which behavior a particular version introduced.

Keep the previous configuration and check what’s selected

First copy the current configuration and any necessary personal entry details, and protect the credentials they contain. On Home, check the current server. In Config, confirm the active file, then check Global Routing and On Demand. An entry appearing in the list doesn’t mean the current selection matches what you used before. A subscription update may rename or remove entries or change their settings at the same time as an app update. Comparing local copies section by section is more likely to reveal the actual difference than resetting everything.

If the issue occurs only with an older configuration, use a copy to undo recent changes or restore verified settings gradually from a minimal working configuration. If the configuration shows a clear error, fix the relevant syntax, section, or policy reference first; don’t ignore the message and pile on more settings. Keep setting names in English when consulting the in-app guide so you can find the right option. After restoring the configuration, test real requests again. Being able to open Config doesn’t mean every setting is suitable for your current network.

Distinguish the same purchase from the same network configuration

On iPad, check the purchase status in the App Store using the Apple ID used for the purchase. See the iPad app guide and restore purchased app guide for steps. A purchase record determines eligibility to get the app; it doesn’t automatically restore local servers, subscriptions, and configurations. If the app offers an import or sync option, confirm its source, contents, and active file. Seeing the app on both devices doesn’t mean their network settings are identical.

To compare an iPhone and iPad, first put both devices on the same Wi-Fi network, use the same existing server and equivalent configurations, then visit the same destination. If one uses cellular and the other Wi-Fi, the results primarily reflect different network routes. Also check whether the iPad is connected to a keyboard, dock, or Ethernet accessory and whether the system is using a different network service. Accessories can change the access route, so DNS, local network access, and On Demand conditions may differ from the original Wi-Fi setup.

Check split-view actions, sleep, and local network access

The iPad’s split view or wider layout may show a list and details at the same time. Editing a file doesn’t necessarily make it the active configuration. Viewing a server doesn’t mean it’s the one selected for connection. After making changes, return to Home and Config to confirm what’s actually selected. When using multitasking, distinguish between the app window reappearing and the connection being re-established. Check the switch, system status, and request results together rather than relying on whether the window is in the foreground.

If failures happen only after waking from sleep, note the network before and after waking, whether sign-in was required, and the On Demand state. Test a manual connection first, then see whether automatic connection works under the same conditions. If local files, printing, or device discovery fail, check system permissions for the relevant access and confirm the destination is still on the same subnet. Some discovery methods depend on multicast; ordinary websites working doesn’t prove local network discovery is working. Don’t delete all routing rules to fix a single local destination.

Reinstall only after you’ve made a backup, compared configurations, and confirmed it’s necessary. Reinstalling may remove local content, but it won’t fix server settings or subscription permissions. Get the app only through the App Store. To verify its authenticity, check the developer name Shadow Launch Technology Limited, the official icon, and app ID 932747118. Afterward, test manual connections, wake from the lock screen, network changes, and the specific task that failed. Record the steps that worked in a brief summary and leave other settings unchanged to preserve a reliable baseline for future troubleshooting.