Official Manual · Troubleshooting

Shadowrocket
Complete Troubleshooting Guide

Identify which layer is failing before changing settings. This official guide is organized by symptom. For first-time setup, follow the quick-start steps in the user manual first, then return to the relevant section. This guide assumes you already have your own subscription or server details; it does not provide, sell, or recommend servers or subscriptions.

A one-time app purchase is not a service plan. The app purchase, server service, and configuration file are separate. For purchase and reinstallation help, see how to get the official app from the App Store; for quick answers, see Troubleshooting. Check the App Store listing for system requirements.

Routing

The toggle is on, but webpages or apps won’t load

Check the underlying network first, then compare Global Routing modes. A VPN-connected status only confirms the device’s connection state; it doesn’t prove that every request has completed DNS resolution, authentication, and data transfer. Choose a page that normally works as a consistent test and note whether all pages fail or just one domain or app. Those patterns point to different causes, so don’t assume the server is down.

Establish a baseline on the underlying network

Disconnect Shadowrocket normally and open the test page on the same network. If it still fails, check whether Wi-Fi requires a sign-in page, cellular data is working, and the app has permission to access the network. Public Wi-Fi can show as connected before access has been authorized. Complete the network’s sign-in or approval steps, then test again. App settings can’t replace the underlying network’s login or authorization.

If the page loads after disconnecting, reconnect Shadowrocket and try the same page again. Don’t change networks and servers at the same time, or the comparison won’t be useful. If only one app fails, check the domains it uses, any network restrictions of its own, and whether the failure happens during sign-in, content loading, or background refresh. A working browser doesn’t mean every request from that app takes the same route.

Compare the three Global Routing modes

If Proxy works but Config doesn’t, check that the correct configuration is selected, the matching policy points to the intended server, and no REJECT rule applies. If Direct works but Proxy doesn’t, check the server details or the path from the server to the destination. This comparison narrows down the cause but isn’t conclusive: DNS, other configuration behavior, and the destination service can also affect results. Check request records alongside the test.

Check rule order, not just for matching keywords

Open Config and confirm which file is actually in use; don’t check only a similarly named file in the list. Rules are generally evaluated in order, and the matching policy is applied. A broad rule placed before a specific one may prevent the specific rule from ever matching. The snippet below illustrates order only. example.com is a sample domain used for syntax, not a service you need to access or a drop-in replacement for your configuration.

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

This snippet checks the example.com suffix first, then evaluates GEOIP, with FINAL as the fallback. PROXY and DIRECT behave differently. If your configuration uses custom policy names, confirm that each name exists and is referenced correctly. Seeing FINAL doesn’t mean every request reaches it; an earlier rule may already have matched. For IP-based rules, also consider when DNS resolution occurs—you can’t infer the final match from the webpage’s domain alone.

Distinguish rule issues from destination service issues

Use available connection logs or diagnostic details to check the failed request’s domain, policy, and error type. If one domain returns the same service-level error through different routes, the cause may be the destination service, account session, or regional service conditions—not a failed tunnel. If the request fails only in Config and the log shows an unexpected policy, fix that rule first. Don’t switch everything to Proxy long-term to hide a routing mistake.

Save a copy of the original file before editing. Change only one setting that could explain the symptom, then test the same destination again. Once verified, return to the Config mode you normally need and check whether other frequently used pages are affected. For configuration sections, see the .conf file structure guide. If the route is as expected but resolution still fails, go to the DNS section rather than adding duplicate rules.

Subscribe

Subscribe update failed, imported list is empty, or content looks wrong

Keep your existing working entries, then check subscription access and content parsing. A Subscribe update involves several steps: reaching the address, authentication, receiving a response, and the app recognizing its contents. An update error doesn’t necessarily mean existing servers have stopped working; don’t immediately delete the entire group. A working client connection and a working subscription update are separate. The subscription may use another host or require different access conditions.

Confirm the address is current and complete

Check the subscription address against the source information you already have. Make sure you haven’t missed part of the query string or copied a period, space, or line break. Identity information in the address may determine what it returns; don’t remove it just to make the URL look cleaner. If the address was regenerated, the old one may no longer work. Use current valid information instead of randomly changing characters in an old address.

Treat the subscription address as a credential. Don’t post it in public support threads, screenshots, or shared documents, and don’t send it to people who don’t need it. When reporting an issue, describe the host access error and status instead. If the address has been exposed, replace the relevant credentials through the original service’s management process. Browser address bars and system share previews may also reveal the full address, so check for unintended exposure before troubleshooting.

Check access errors separately from content errors

If an update reports a connection timeout, resolution failure, or certificate error, check the subscription host using the network and DNS sections. For a clear identity or access-permission error, check your original information to confirm the subscription is still valid. Access to one webpage doesn’t prove the subscription host is reachable; connecting to the subscription host doesn’t prove it will return content the app can use.

The response might be a sign-in page, an error message, or another format—not a server list. If the update completes but adds no entries, confirm that the format from your existing service is supported by Shadowrocket and check whether the response is empty. Don’t change the protocol type to import webpage text as server details. Redirects, account changes, or format updates can cause the same address to return different content.

Understand the different roles of Subscribe and Config

A server subscription provides or updates server entries; a configuration file in Config contains rules and related settings. They’re related but not interchangeable. Importing a server list doesn’t create correct routing rules, and loading a .conf file doesn’t validate credentials. If your information includes both types of address, use each for its intended purpose instead of repeatedly trying a configuration URL in Subscribe.

If entry names or counts change after an update, compare them with the latest information from your existing service. Servers may have been renamed or replaced, and the previously selected entry may no longer exist. Check which entry is actually selected on Home. If custom policies reference fixed names, confirm those names still resolve. A shorter list alone doesn’t prove a parsing error; check what the source returned first.

Check the route used for the update request

If regular webpages work but Subscribe updates fail, check whether Shadowrocket was connected during the update and how the subscription host was reached. Settings and configuration can affect the request’s outbound route. First disconnect normally and try once on the underlying network, then reconnect under the original conditions and compare. Keep the address unchanged; don’t switch networks, replace the address, and edit rules all at once.

If the content is available through only one route, address the subscription host’s access conditions rather than changing every server setting. If both routes return the same permission error, check the source account or address validity. For redirect or certificate issues, keep the exact error and ask the original information provider to confirm it. Don’t weaken verification requirements to hide the failure.

Checks to perform after an update

After a successful update, reselect the intended entry, check Global Routing and policy references in the configuration, and test actual access. A successful subscription refresh only confirms the list updated; authentication can still fail afterward. If the list issue is fixed but connections time out, go to the server section. For help locating the import controls, see the user guide instead of using group deletion as a troubleshooting step.

DNS

DNS resolution failed, domain won’t load, or an unexpected address was returned

First distinguish name resolution from what happens afterward. Web access usually starts by resolving a domain to an address, then establishing a transport connection and application session. A failure at any step can look like a page that won’t load. A successful Connectivity Test doesn’t prove a webpage failure is caused by DNS. Check DNS settings only when the error text, request record, or a repeatable comparison points to the resolution stage; don’t use a different resolver to mask authentication or routing problems.

Identify what failed and at which stage

Record the domain that won’t load and whether it’s the destination website, proxy server hostname, or subscription hostname. They may use different routes. If the server hostname can’t be resolved, the tunnel itself may fail to connect. If the tunnel is up but the destination domain fails, check that request’s resolution and routing. Avoid describing every failure as “DNS is down,” or later tests will be hard to interpret.

Try another commonly used domain on the same network, then compare on the underlying network. If only one domain fails, the cause may involve its records, cache, Host mapping, or a specific rule. If several unrelated domains fail, check whether the resolver is reachable. Opening a site by IP address isn’t a reliable general-purpose test: the certificate, Host header, or virtual host may still require the correct domain.

Check DNS and Host settings in the active configuration

First identify the Config file actually in use, then check existing DNS-related settings and the Host section under General. Changing an option in Settings doesn’t automatically mean file-level settings no longer affect behavior. Refer to the app’s current guidance for each option’s scope. Record the original values and note which settings come from the file versus the app so you can restore the test setup.

A fixed Host mapping can keep a domain pointed at one address. If that mapping is outdated, changing the DNS service won’t change the fixed result. Confirm what each mapping is for, then temporarily remove only the relevant entry to compare; don’t clear the whole Host section. Keep a way to restore any mapping required by the information you already have, and don’t overwrite it with an address found through a search.

The resolver itself needs a reachable route

Entering a DNS server address doesn’t guarantee it can be reached. Standard queries, encrypted queries, and queries routed through a proxy each require an appropriate network path. If a configuration sends DNS through a proxy, but the proxy server hostname depends on that same unresolved route, the settings can create a dependency problem. Identify which hostname must be resolved first; don’t force every query through a route that can’t start.

Use DNS settings you already understand and can verify on the current network. Adding many servers doesn’t necessarily make resolution more reliable; different responses and fallback timing can make the issue harder to reproduce. Save the original value and change one setting at a time. If results improve, check that everyday routing and local network access still work.

Check IPv4, IPv6, and caching separately

A domain may return both IPv4 and IPv6 addresses. Resolution can succeed while one address family remains unreachable, causing long waits before fallback or failures for some resources. That’s an address reachability issue, not necessarily an unresponsive resolver. Check the error and the network’s current capabilities, then compare the relevant path. Don’t permanently disable device-wide networking capabilities to work around one destination.

After changing DNS or Host settings, existing connections or cached results may still be in use. End the current test, disconnect and reconnect normally, then try the same destination again; reopen the destination app if needed. Don’t make several changes in a row and judge the result using an old page. If it works briefly and then fails again, record the domain and timing, and check for a configuration switch or network change.

DNS results can also affect rule matching

DOMAIN rules match domain-based conditions; IP-CIDR, IP-CIDR6, and GEOIP involve address-based conditions. The exact behavior also depends on rule parameters and when resolution occurs. A request may match a different policy when it resolves to another address. Confirm the matching rule before troubleshooting; moving every IP-based rule ahead of domain rules won’t “fix DNS.” FINAL is a fallback for requests that don’t match earlier rules—it can’t correct an invalid resolution result.

After a fix, test the affected domain, one regularly used domain, and any essential local network service. If the DNS error is gone but access still fails, return to the routing section to check the next connection stage instead of changing DNS again. For more symptom comparisons, see the DNS resolution troubleshooting guide. When reporting the issue, include the exact error and setting categories, but hide internal domains and private addresses.

iPad

iPad purchase restoration, layout, and network troubleshooting

On iPad, handle purchase restoration and configuration transfer separately. Use your own Apple ID that you used to purchase the app to redownload the app from your App Store purchases. Check the App Store listing for purchase eligibility and system requirements. Redownloading the app doesn’t automatically transfer servers, Subscribe entries, or Config files from another device. If the list is empty after opening the app, check data transfer first instead of assuming the purchase failed.

How to check if the app still shows a price after purchase

Check whether the account currently used for App Store purchases is the original purchase account; don’t rely only on the account shown for other system services. Then verify the product name, developer Shadow Launch Technology Limited, and app ID 932747118. Don’t buy again before confirming the account and product. For verification, see the three checks for the official app. The App Store is the only way to get the app.

If purchased items aren’t currently showing in the store, check your network, purchase history, and current storefront, then follow the prompts shown in the App Store. Family Sharing availability depends on the store listing and your own family settings; another person’s purchase may not be restorable. App purchases and server services are separate. After restoring the app, use your own valid connection details.

Finding controls in landscape, Split View, or a narrow window

Landscape orientation or Split View can change where lists and details appear. Find controls by their English labels—Home, Config, Data, and Settings—not by instructions such as “the third button in the bottom-left corner.” An editor may still show a previously selected item. Verify the entry name and address before editing, then check the selected item again after saving so you don’t change a neighboring entry with the same name.

Rotating the screen or resizing a window doesn’t automatically mean the routing state has changed. If the interface looks different, check the current Global Routing mode and the file actually selected in Config. When entering server details, an external keyboard, autocorrect, or pasted text may add spaces. Verify the address, port, and identity fields after saving; a lack of typing errors doesn’t prove the details are valid.

Same details on two devices, different results

Keep the Wi-Fi, destination, and server details the same before comparing results. Don’t compare an iPhone on cellular with an iPad on Wi-Fi as if only the client differed. Even when both devices show the same entry name, the password, transport settings, selected policy, or configuration file may differ. Compare fields by category; don’t send full credentials to a third party for comparison.

If the configuration is identical but only one device fails, check that device’s network permissions, other VPNs, management restrictions, system time, and DNS environment. A Wi-Fi-only iPad can be tested on another network you control. If you use a personal hotspot, also record any network changes on the hotspot device. If changing networks fixes the issue, that shows the access environment is involved; it doesn’t prove an app setting was fixed.

Sleep, wake, and network changes

Note whether the issue occurs after a long period with the screen locked, immediately after waking, or after switching Wi-Fi networks. The underlying network may not be ready immediately after wake, so app requests and VPN reconnection can fail at the same time. Wait until the network is stable, then try one manual request. If you need to reconnect after every wake, check On Demand conditions, system VPN status, and server session behavior, following the connection section step by step.

Time spent in the background doesn’t prove that a connection stayed up, and an old status shown on screen doesn’t prove current requests will work. Compare actual access, system status, and error records. For a failure that occurs only in Split View, check whether the destination app has its own session or network restrictions. Repeat the same action in full-screen mode without changing anything else to see whether the window layout is actually relevant.

Restore migrated settings one at a time and verify each

After restoring data from a backup you control, check that Subscribe is valid and the intended server is selected, then verify the Config file and policy references. If the file references fixed names, a naming difference on the other device may cause rules to match incorrectly. Restore in this order: confirm the data is complete, establish a connection, complete a real request, verify the rules serve their intended purpose, then restore On Demand and extra processing. Don’t enable every complex setting at once.

Include at least one everyday webpage, one existing task that requires a proxy route, and one check of the underlying network after a normal disconnect. If a particular step fails, return to its section rather than repeating the entire purchase process. For account recovery and layout tips, see iPad purchase restoration and usage tips. For help locating controls, see the English interface terms guide.