If you already have a provider and subscription, start by refreshing it manually from Home and checking the result. Then decide whether to enable Update On Open. This guide uses Shadowrocket on iPhone and iPad as an example and explains how to distinguish request failures, parsing errors, and connection problems after an update. The same troubleshooting approach applies to Mac, Windows, Android, and Linux; menu locations vary by platform.
1. What a Subscription Update Changes—and What It Doesn’t
A subscription update fetches the existing subscription URL again and imports the server entries in the response into the relevant group. If your provider changes addresses, ports, or the list of entries, the client must fetch the subscription again to show those changes. A successful update does not mean every entry can connect, nor does it renew your provider account.
Server subscriptions in Home and rule configurations in Config are separate types of content. Updating a server subscription does not also update rules such as DOMAIN-SUFFIX, GEOIP, IP-CIDR, or FINAL in a Config file. First identify which layer is causing the problem; repeatedly changing rule configurations will not refresh server entries.
2. Refresh a Subscription Manually from Home
Refresh manually after importing a subscription for the first time, when your provider announces changes, or when the list appears unchanged for a long time. Before refreshing, note the name of the target subscription group. If you have multiple subscriptions, check the same group afterward; don’t rely only on the server currently selected at the top of Home.
- Open Home. Make sure a subscription group is listed. A server added manually is not a subscription; without a subscription URL, refreshing cannot create a remote list.
- Pull down and release. Wait for the subscription refresh request to finish. Don’t repeatedly pull down while it’s in progress, or it may be hard to tell which request produced the result.
- Check the target group. Confirm that entries are still listed, check whether their names have changed, and look for any error message. Each subscription can succeed or fail independently; changes in one group don’t mean all groups have updated.
- Select a working entry and test the connection. If the previously selected entry was removed, choose another from the updated list. Verify that the subscription was fetched first, then test access separately.
An unchanged entry count alone doesn’t prove the update failed. The remote list may have changed only an address or port, or the provider may not have published anything new. Likewise, an increase in the number of entries only means a different list was fetched; it does not replace a connection test. Don’t delete all subscriptions to test a refresh, as you would also lose the original groups and URL details needed for troubleshooting.
3. Enable Update On Open and Understand What It Does
On iPhone and iPad, find and enable Update On Open under Settings → Subscribe. This triggers a subscription update when you open the app, which can help ensure a newer list is available when you go to Home. If the wording differs, confirm that the option specifically updates subscriptions when the app opens; don’t enable a different feature by mistake.
- Go back to Home and refresh manually once to confirm the URL works.
- Go to Settings → Subscribe → Update On Open and turn it on.
- The next time you reopen the app, wait for the subscription request to finish, then check the group. Don’t judge the result solely by whether the list changes immediately.
- If the same error appears every time you open the app, troubleshoot the network or URL below first. Repeatedly toggling the setting won’t fix the underlying issue.
Update On Open is not a background refresh on a fixed schedule, nor does it push updates as soon as your provider publishes new content. Don’t assume a subscription has refreshed while the app remains in the background, the device is locked, or the system limits background activity. To check the current content, return to Home and refresh manually.
| Setting or action | What it does | What it doesn’t guarantee |
|---|---|---|
| Pull down to refresh in Home | Requests subscription content | That every server has passed a connection test |
| Update On Open | Triggers a subscription update when the app opens | A scheduled update while the device is locked |
| Settings → On Demand | Starts a VPN connection when specified conditions are met | Automatically fetches or repairs the subscription list |
Bottom line: Verify a manual refresh before enabling automatic updates
If a manual refresh still fails, first fix the fetch path for the same URL. Automatic updates only change when the request is triggered; they can’t fix an expired token, an error response, or an issue with your provider account.
4. Troubleshoot Update Failures: Check the Network, URL, and Provider
First distinguish between not receiving a valid response and receiving content that can’t be parsed. The former usually calls for checking the network, DNS resolution, and request path. The latter calls for checking the URL and whether the remote server returned subscription data, a login page, or an error page. Changing protocols based only on a generic “failed” message often misses the cause.
- Check your network connection. Make sure your Wi-Fi or cellular connection has internet access. If the network requires a sign-in page, complete authentication first. Try refreshing on a different network, changing just one factor at a time.
- Check the route used for the update request. If the subscription domain can’t be reached directly on your current network, but an existing server connects successfully, check Update via Proxy under Settings → Subscribe. Enable it and try again while connected to the working server. If you don’t have a working connection, this option won’t solve the initial fetch problem.
- Check the full URL. Copy the subscription URL again from your provider account and verify the scheme, domain, path, and query parameters. Don’t paste in the account login page, page title, or explanatory text.
- Check your provider’s status. In your account, confirm the expiry date, usage, whether the subscription was reset, and whether there are any maintenance notices. If a token was reset, the old link may no longer work; replace it as instructed by your provider.
https://example.com/sub?token=xxxxThe example above shows the URL structure only; it is not a working subscription. Parameters after ? are part of the URL, so don’t remove them just because they look complicated. Don’t add parameters or change ports yourself, either. Subscription URLs often contain access credentials; redact the entire token before sharing screenshots or troubleshooting notes, and never publish the original URL.
Error: The request timed out.
Cause and fix: The request didn’t finish within the allowed time, possibly because of the network or remote server response. Retry on a network confirmed to have internet access, then check whether you need to update through an existing working connection. Don’t refresh repeatedly in quick succession.
Error: A server with the specified hostname could not be found.
Cause and fix: The hostname in the request could not be resolved. First check that the subscription domain was copied correctly, then try another network. If it still fails, ask your provider whether the domain has changed.
Error: Failed to load subscription
Cause and fix: The subscription did not load, but this message alone doesn’t identify the cause. Verify that the URL is complete and your account is active, then check whether the response is a login page or an error page. Note any more detailed message shown with the error.
The English messages above are examples that can help identify the type of problem. Actual messages may vary by system and point of failure. For HTTP 401 or 403, first check authorization, the token, and access restrictions. For 429, stop retrying rapidly and wait as directed by the remote service. These status codes are troubleshooting clues, not proof that an account has expired.
5. Update Succeeds but the List Is Empty or Connections Still Fail
A successful subscription request only means the fetch completed. The remote server may return an empty list, text in an unsupported format, or even a web page with a successful status. If the list is empty, check that your provider gave you a subscription URL compatible with Shadowrocket. A URL opening in a browser doesn’t prove that its contents are in the right format.
- Only one group is empty: Check that group’s URL and the status of its associated account first. There’s no need to clear other groups that are working.
- Entries are listed but won’t connect: Make sure the selected entry is still valid after the update, then check your device’s network and availability on your provider’s side.
- Web traffic isn’t routed as expected: Check Home → Global Routing. Config routes traffic according to its configuration rules; Proxy and Direct use proxy and direct connections, respectively. Scene contains scene-related settings; it is not a subscription refresh control.
- Thought a refresh would fix the rules: Check the currently enabled configuration in Config separately. The server list and rule file are managed independently; updating one doesn’t update the other.
Protocol names don’t identify the cause of a failure. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, or WireGuard entries in a subscription must match the settings provided by your provider. Don’t change the protocol, TLS, or transport options at random just to make an update succeed. A subscription fetch failure occurs while loading the list; it is a different issue from an individual entry failing to connect.
6. Subscription Update FAQ and Troubleshooting Notes
Updates fail every time I open the app. Should I turn off automatic updates?
You can turn off Settings → Subscribe → Update On Open to reduce repeated errors, then refresh manually from Home and note the error. Turn it back on once the URL and network are working. Disabling it only pauses the trigger; it doesn’t fix the subscription.
The names and entry count didn’t change after refreshing. Did the update fail?
Not necessarily. Your provider may not have changed the list, or may have changed only internal parameters for some entries. Check whether the refresh reported an error, then confirm with your provider that changes were published. Don’t repeatedly delete and re-add the subscription to test it.
Do I need to connect to a proxy to update a subscription?
No. It depends on whether the subscription domain is reachable on your current network. Try a normal refresh first. Only check Update via Proxy if a direct request fails and you already have a working connection. This option isn’t required for every subscription.
My provider gave me a new URL. What should I do with the old group?
First save the old group name and any necessary notes, then update the relevant subscription URL using the information from your provider. Refresh manually once and confirm that the list and connections work before removing duplicate groups. Don’t share both sets of credentials for comparison.
If you still can’t pinpoint the problem, collect a brief troubleshooting record: when it happened, whether you were on Wi-Fi or cellular, the exact error, whether a manual refresh failed, the status of Update via Proxy, and whether other groups work. This will help your provider check your account and the subscription response more effectively than a vague “it won’t update” report. Don’t include your full subscription credentials.