For iPhone and iPad users who have imported their own subscriptions into Shadowrocket. This guide covers manual refresh from Home, Update on Open in Settings → Subscribe, and how to distinguish an invalid URL, a failed request, and unparseable content. Check the refresh result—not the connection toggle—to determine whether an update succeeded.
First, identify the problem: fetching a subscription or using an existing configuration
Subscription updates follow a separate process: Shadowrocket requests the saved subscription URL, receives a response, parses it, and updates the entries on Home. If the previous entries are still visible on Home, that only means the data from the last successful import remains on the device; it doesn’t confirm that the latest request succeeded. Likewise, a failed update doesn’t necessarily mean every existing connection has stopped working. Check these issues separately.
Before troubleshooting, note which subscription failed and the exact message shown during refresh. If you have multiple subscriptions, refresh them one at a time; don’t use the result for one group to judge every URL. Compare the entry count and update time before and after refreshing. If the message disappears but nothing changes, the provider may have returned the same data. If an error appears and the old entries remain, the update didn’t provide usable new content.
How to diagnose the issue: check the refresh result first
Identify the subscription, note the message, and check whether the old entries are still there before checking the connection. Toggling the Home connection switch repeatedly is not a substitute for testing a subscription update.
Manual refresh: update each subscription and check its saved URL
Manual refresh is a good first troubleshooting step because you can check the result immediately for each subscription. These steps assume you already have your own subscription URL. The sample URL https://example.com/sub?token=xxxx illustrates the URL structure; it is not a usable subscription. Refresh using your own saved URL, and make sure it is complete.
Find the subscription
Open Home in Shadowrocket and find the Subscribe entry you imported earlier. If Home has multiple groups, identify the one you want to update to avoid mistaking another group’s successful refresh for a fix.
Refresh manually
Pull down on the subscription in Home to refresh it, then wait for the request to finish. Don’t repeat the action before a message appears. Note the exact error text and compare the entries before and after the refresh.
Check the URL
Open the subscription’s edit screen, confirm that Type is set to Subscribe, and check the saved URL. Look for missing, expired, or extra spaces in the domain, path, and query parameters such as
token. Save any corrections, return to Home, and refresh again.Record the result
If only one group fails, check its URL and response first. If every subscription times out, check your current network. Keep the exact error text so you can ask your own service provider to verify the URL.
If you haven’t imported a subscription yet, tap “+” in the upper-right corner of Home, set Type to Subscribe, enter a URL you already have, and save it before refreshing for the first time. When copying the URL, include all parameters after the question mark. For example, ?token=xxxx in the sample URL is part of the URL; leaving it out may result in access being denied or unexpected content. Don’t share real URLs or their credentials publicly.
Update on Open: settings and when to use it
Update on Open attempts to fetch new subscription content when you open Shadowrocket. It doesn’t refresh continuously in the background and can’t fix an invalid URL. First, complete a manual refresh successfully. Then go to Settings → Subscribe and look for the option to update when opening the app. If Update on Open is available in your version, enable it as needed. The options shown in the app may vary.
Verify the URL first
Return to Home and manually refresh the target subscription. Confirm that no error appears and that the subscription content is displayed. If the manual refresh fails, troubleshoot the three causes below instead of repeatedly retrying with automatic updates enabled.
Check the settings
Go to Settings → Subscribe and look for Update on Open or other options related to updating when you open the app. Return to Home after making changes. If you manage multiple subscriptions, check the refresh result for each one.
Check again
The next time you open the app, wait for the network request to finish, then compare the subscription content or check for an update message. Opening the app doesn’t guarantee that the server returned new entries; the list may stay the same if the provider’s content hasn’t changed.
If your subscription URL is reachable only through an existing proxy connection, check Update via Proxy in Settings → Subscribe and test it based on whether the current connection works. This option changes the network route used for the update request; it won’t replace an invalid URL or make an unparseable response usable. Change one condition at a time: try the current route first, then enable or disable the option and manually refresh again to compare the results.
The rule of thumb: automatic updates depend on a successful manual refresh
Enable Update on Open only after a manual refresh confirms the content can be fetched and parsed. If the manual refresh fails, keep the error message and check the URL, network, and format one at a time.
Three common causes of update failures and how to troubleshoot them
Error messages vary depending on the request stage and server response. The English messages and status codes below are examples; check what actually appears on your device. The same “Failed to load subscription” message can have several causes, so it doesn’t by itself prove that a URL has expired.
Error: HTTP 403
Cause and fix: The server rejected the request, possibly because of the URL credentials or access restrictions. Check that the subscription URL includes all its parameters, and ask your own service provider to confirm the access requirements. Don’t guess or change the credentials.
Error: HTTP 404
Cause and fix: The requested resource wasn’t found. Check that the domain and path match the URL you saved. If the original URL has changed, ask your own service provider to confirm the current valid URL before refreshing.
Error: The request timed out.
Cause and fix: The request didn’t finish in time. First check that you can access the internet over Wi-Fi or Cellular. Then compare manual refresh results using a direct connection and Settings → Subscribe → Update via Proxy.
Error: Failed to load subscription
Cause and fix: The app couldn’t retrieve or use the subscription content. Check the URL and network first. If the request completes but no usable entries appear, ask your own service provider to confirm that the response uses a format Shadowrocket can parse.
Invalid URL: check the address, then verify access
If only one subscription fails, especially after a recent change to its saved URL, check the URL first. The domain spelling, trailing path, and query parameters can all affect the server response. HTTP 403 points to an access issue; for HTTP 404, check the path first. The server may also report the same problem with a different status code. Don’t delete old entries that still work to test the URL. Keep the current setup and ask your own service provider to verify it.
Network issues: check device connectivity and the route used for the subscription request
A Wi-Fi or Cellular connection doesn’t guarantee that the subscription URL is reachable. First confirm that the device can access the internet, then manually refresh from Home on the same network. If every subscription times out, check the network. If only a specific URL times out, check its access requirements. Before changing Update via Proxy, make sure the selected connection works; otherwise, the update request may still fail.
Can’t parse the content: check the response, not the filename
Even if the request reaches the server, the response may be a login page, an error message, or empty content—not subscription data Shadowrocket can parse. You may see no new entries after refreshing or get a loading error. Repeatedly switching Global Routing between Proxy, Direct, and Config won’t fix the server response. Confirm that Type is set to Subscribe, then ask your own service provider to check the actual response format for the URL.
Frequently asked questions: no visible change after refreshing
No error after pulling to refresh, but the entries haven’t changed?
First make sure you refreshed the intended subscription, not another group in the list. Then check the content currently provided by your service provider. If the remote entries haven’t changed, a successful refresh won’t add anything to the list. An unchanged entry count alone doesn’t mean the refresh failed.
Why try a manual refresh if Update on Open is already enabled?
A manual refresh lets you match a specific action to its result. Return to Home, pull down on the target subscription, and note the exact error text. If it still fails, check the URL, network route, and response content in that order instead of waiting until the next time you open the app.
Still timing out with Update via Proxy enabled?
First make sure the connection selected on Home is working, then check the option’s status in Settings → Subscribe. If both request routes time out, note when it happened and the error message, then ask your own service provider to confirm the subscription URL’s access requirements.
The URL opens, but loading still fails?
Being able to open a webpage doesn’t mean the response is a subscription Shadowrocket can parse. Check that Type is set to Subscribe and the URL is complete. Ask your own service provider to verify the content returned by the URL; a login or error page can’t be imported as subscription entries.
Will a failed update delete my existing entries?
Check Home to see whether the existing entries are still visible. Don’t assume one failed update rewrote your entire configuration. Note what actually changed before and after the refresh, and avoid deleting an old subscription to troubleshoot until you know the new URL works.
After troubleshooting, manually refresh once more to confirm that the target subscription returns usable content. Then check the result the next time you open the app. Subscriptions are provided by each user’s own service provider. Shadowrocket is a paid client for Apple platforms that imports and uses these configurations; purchasing the app does not include a service plan. For iPhone and iPad system requirements, refer to the App Store listing.