When a Shadowrocket subscription update fails, keep your existing entries, try a manual refresh, note the message, then check the URL, network path, and response format. This guide assumes you already have a provider and subscription. It covers refreshing from Home, the automatic update setting under Settings → Subscribe, and how to distinguish a subscription update failure from a server connection failure. The steps use the iPhone / iPad interface; menu locations may vary on other platforms.
First, distinguish subscription updates from connection tests
A subscription update sends a request to the subscription URL and parses the response into server entries. A connection test uses the address, port, and protocol settings of an existing entry to establish a connection. These are separate checks. A working existing server does not mean the subscription URL is still valid, and a successful refresh does not mean every server in the list can connect.
Home shows server entries and connection status; Config is mainly for managing rule configuration files. Do not confuse updating a remote configuration in Config with updating a server subscription in Home. Before troubleshooting, identify which item failed so you do not replace an entire rule file to fix a subscription.
Manually refresh a subscription in Home
Start troubleshooting with a manual refresh so you can see the result directly. Do not delete the subscription first: existing entries may still connect, and deleting them could leave you without anything to test if you cannot retrieve the list again. Note the subscription group name, current entry count, and error message before following these steps.
-
Identify the group
Open Home and find the subscription group you need to refresh. If you have multiple subscriptions, confirm which one you are checking; changes in another group do not mean this update succeeded.
-
Check the URL
Open the subscription’s edit screen and make sure the URL is complete. To add one for the first time, go to Home → “+” in the top-right corner → Type → Subscribe. If the entry already exists, edit it instead of creating a duplicate.
-
Pull to refresh
Return to Home, pull down from the top of the list, and release to refresh the subscription. Wait for the request to finish, then read the success or error message. Repeated refreshes may increase the chance of rate limiting.
-
Check the result
Check whether the target group still has entries and whether its name and count look as expected. If the refresh succeeds but the count stays the same, the remote content may simply be unchanged; the count alone does not indicate failure.
If the list becomes empty after an update, stop refreshing. Note the message and ask your provider whether the subscription returned an empty list or whether the available entries changed. Adding the same URL again will not fix an issue with the remote content.
Enable Update on Open
Go to Settings → Subscribe, find Update on Open, and turn it on. This setting attempts to refresh subscriptions when the app opens, and is best used after you have confirmed that manual updates work. Leave the app, open it again, and check the result. Switching between Home and Config alone is not a reliable way to verify automatic updates.
- Manual first, automatic second: If a manual refresh still fails, troubleshoot the request first. Automatic updates cannot fix an expired URL or an invalid response.
- Automatic does not mean scheduled: Update on Open does not make the app send recurring requests in the background while it is closed. System background scheduling, network conditions, and app state can all affect when it runs.
- Proxy routing is a separate setting: Settings → Subscribe → Update via Proxy controls whether update requests try to use a proxy. It does not control when Update on Open runs.
- Check On Demand separately: Settings → On Demand manages conditional connection behavior. It does not repair a subscription URL or act as a subscription update timer.
If updates fail only when you reopen the app but succeed after waiting a few seconds and refreshing manually, check whether the device has finished connecting after switching between Wi-Fi and mobile data. Temporarily turn off Update on Open, wait for the network to stabilize, then try a manual refresh to distinguish a startup timing issue from a URL problem.
Check the URL and access permissions based on the error
Error messages vary with the system language, network layer, and server response. The examples below explain common messages and status codes; you may not see exactly the same wording every time. Recording the original message is more useful than simply noting “update failed.”
Error: The request timed out.
Cause: The request did not finish within the allowed time. The connection may be unavailable, the remote server may be slow to respond, or the proxy path may not work.
Try this: Switch between Wi-Fi and mobile data, then test direct and Update via Proxy paths separately. Change one setting at a time.
Error: A server with the specified hostname could not be found.
Cause: The subscription hostname could not be resolved. The domain may be misspelled, DNS may be failing, or the domain may no longer be active.
Try this: Check the full domain name and try another network. If the problem persists, ask your provider to confirm the current subscription domain.
Status code: HTTP 403
Cause: The server refused access. This may be related to the URL token, account permissions, or restrictions on the request source.
Try this: Check the subscription status and latest URL in your own service account. Reinstalling the app repeatedly is not a troubleshooting step.
Status code: HTTP 429
Cause: The server is limiting requests made in a short period. Automatic refreshes from multiple devices may also trigger the limit.
Try this: Stop refreshing repeatedly, wait as directed by the server, and reduce duplicate requests from other devices.
Subscription URLs often contain account credentials. When checking one, make sure the parameters after the question mark are complete, that there are no spaces or line breaks, and that the URL was not truncated by a messaging app. The example below is for identifying the URL structure only, not a working subscription address. Hide the actual token when sharing troubleshooting details.
https://example.com/sub?token=xxxx
Check the update request path when the network is unavailable
Being able to open regular webpages does not prove that the subscription domain is reachable. Different domains may use different DNS results, access restrictions, or network paths. Keep the current settings and refresh the same subscription over another network. If it fails only on one network, troubleshoot that network rather than immediately changing every server setting.
- Note the current setting for Settings → Subscribe → Update via Proxy, then refresh once without changing it and record the result.
- If direct updates fail but an existing server still connects, select a confirmed working entry in Home and connect through it. Then enable Update via Proxy and try again.
- If updates through the proxy fail, turn off Update via Proxy and test a direct connection. Do not assume that using a proxy will always work better than connecting directly.
- Check whether Global Routing is set to Proxy, Direct, Config, or Scene, and note the mode used for this test. An enabled connection toggle alone does not prove that every request goes through a proxy.
- If you see a certificate or secure connection error, check that the device’s date, time, and time zone are correct. Do not bypass verification by ignoring certificate errors.
When using Config, rules may affect where the request goes. Do not add broad DIRECT or PROXY rules just to test a subscription. Make small, reversible changes to identify the cause before deciding whether to adjust the configuration.
Request succeeds but parsing fails: check the response format
A successful HTTP request only means a response was received; it does not guarantee that the response is a valid subscription. The server may return a login page, access instructions, a verification page, or empty text, sometimes with HTTP 200. Repeatedly tapping Update will not turn a webpage into a server list.
| What you see | Check first | What to do |
|---|---|---|
| Parsing fails after the request completes | Whether the URL is a client subscription, not an account management webpage | Copy the correct subscription URL again from your service account, then edit the existing entry. |
| It worked before, but failed after a format change | Whether the server changed the output format or added unsupported fields | Tell your provider you use Shadowrocket and share a redacted error message to confirm a compatible format. |
| Update succeeds, but the number of entries drops | Whether the remote server deleted entries, changed account permissions, or returned an empty list | Check your account status and the remote content first. Do not assume the problem is a local parsing error. |
| The list looks normal, but servers cannot connect | Server address, port, protocol settings, and whether the entry is still valid | Switch to connection troubleshooting instead of repeatedly refreshing the same list. |
Do not copy an entire error page into Add Server. Shadowsocks, VMess, VLESS, Trojan, and other entries have their own fields; subscription parsing and manual entry are different operations. If you need to enter details manually, get the exact settings from your provider rather than guessing the protocol or port based on webpage text.
Frequently asked questions and troubleshooting notes
Why did the update fail if my old servers still work?
The subscription URL and server address are different request targets. Keep your existing entries, test a connection from Home, then check the subscription URL’s permissions and network path separately. Do not delete the entire group first.
Why is my list still old with automatic updates enabled?
First, pull down to refresh in Home and read the message, then check Settings → Subscribe → Update on Open. If the request succeeds but the list does not change, confirm that the server has actually published new content. An unchanged name and entry count do not, by themselves, mean automatic updates failed.
Will copying the old URL definitely work after I get a new phone?
Not necessarily. The URL may have been reset, or access may be limited by account permissions or request frequency. Confirm it is still valid in your service account, then add it via Home → “+” → Type → Subscribe. Do not post a complete URL containing a token in a public discussion forum.
Should I reinstall Shadowrocket after an update fails?
Do not reinstall it yet. Save your configuration and subscription entries, then test another network, check the URL, and switch the update path. Consider further steps only if you have identified a local app state issue. Reinstalling will not change a server’s refusal to grant access.
When contacting your provider, include the failure time and time zone, network type, exact error message, whether Update via Proxy was enabled, and what happened on another network. Send account or URL details only through the provider’s private support channel. This site does not provide, sell, or recommend servers, subscriptions, or VPN services; it covers client settings and troubleshooting only.