Shadowrocket Subscription Update Guide: Manual Refresh, Update on Open, and Troubleshooting

What a subscription update does: refreshes the list, not the connection

A Shadowrocket subscription update makes a new request to the saved subscription URL and adds the parsed entries to Home. When your service provider changes server addresses, ports, authentication details, or entry names, the app usually needs to fetch the subscription again to receive those changes. Buying the app is separate from a service plan; this guide assumes you already have your own subscription.

A successful update only means the subscription was fetched and parsed. It doesn’t mean every entry can connect, or that your active connection has switched to a new entry. The subscription list, rules in Config, and the system VPN connection are separate settings. Check them separately when troubleshooting.

A Subscribe entry added in Home is a subscription source. A server entry imported on its own may not have a subscription URL, so it can’t fetch future changes as a subscription would. Updating a remote configuration file in Config is also separate from updating the subscription list in Home. Before proceeding, confirm which type of content you’re maintaining.

Manual refresh: find the subscription, then update it

Use a manual refresh first when importing a subscription, after your service provider announces configuration changes, or when the list hasn’t changed after an automatic update. This lets you trigger a request and check the result right away. Labels may vary with the app’s language, so this guide uses the English interface terms. The subscription group controls may also move with layout changes.

1. Find the subscription

   Open Home, find the subscription group, and confirm its name. If you haven’t imported it yet, tap “+” in the upper-right corner of Home → Type → Subscribe, enter your existing subscription link in URL, and save.

2. Check the URL

   Open the subscription’s edit screen and make sure the URL is complete, especially the parameters after the question mark. When copying it, don’t include spaces, line breaks, non-ASCII punctuation, or explanatory text. Return to Home after checking it.

3. Trigger an update

   Pull down at the top of the Home list to refresh. To update one subscription, long-press its group and choose Update. Use the options shown for that group in your current version of the interface.

4. Check the result

   Wait for the request to finish and look for an error message. Then expand the target group and check whether entry names, the entry count, or known changes are reflected. Don’t repeatedly refresh while a request is still in progress.

5. Check the connection

   Make sure the currently selected entry is still in the updated list. If your service provider replaced it, select a valid entry and test the connection separately. If you have an active session, save your work before changing the connection.

An unchanged entry count doesn’t necessarily mean the update failed: the server may have changed authentication details for an entry without changing its name, or returned the same content as before. Likewise, a higher count doesn’t prove every entry works. Compare the results with the changes your service provider announced rather than relying on the number alone.

Update on Open: where to find it and when to use it

The usual path to automatic updates is Settings → Subscribe → Update on Open. When enabled, the app will try to update subscriptions when the option’s conditions are met. If the current interface offers additional limits, such as an update interval, check those too. Don’t assume that every time you bring the app back to the foreground it will make a new request.

This setting is useful if you want to fetch subscription changes when you open the app, but it depends on the subscription server being reachable over the current network. It doesn’t guarantee scheduled system background tasks or continued subscription fetching while the device is locked. If the option name or menu path differs from this guide, follow the description shown under Subscribe in Settings.

Settings → On Demand triggers VPN connections based on conditions. It’s separate from automatically fetching subscriptions. Enabling On Demand alone doesn’t mean subscriptions will update automatically; enabling Update on Open doesn’t grant system VPN permission or guarantee that a connection will work.

Manual vs. automatic updates: choose based on how you maintain subscriptions

Both methods fetch from the same subscription source. The main differences are when they run and how easy it is to observe and troubleshoot the result. Automatic updates can’t revive a dead link or change the format returned by the subscription server. If something goes wrong, leave the automatic setting as it is and make one manual request you can observe; it’s usually easier to find the cause that way.

• Subscriptions rarely change: refresh manually when needed; there’s no need to make repeated requests.
• Subscriptions change often: verify the link first, then consider enabling Update on Open.
• Your service provider limits request frequency: follow their update interval and avoid triggering updates repeatedly.
• Need to preserve local changes? Record anything important before updating. Entries generated from a subscription may be overwritten by the next update, so don’t rely on them as a permanent place for manual edits.

Subscription update troubleshooting: read the error, then check the relevant step

First note when the error occurred, which network you were using, which subscription you targeted, and the message shown. Common network-level errors are listed below in their original English wording. The interface may show localized text or additional details; respond to the meaning of the message. An error describes where the request failed, but doesn’t by itself prove there’s a problem with your provider account or a particular server.

Check HTTP status and response content separately

• HTTP 401: The request usually lacks valid authentication. Check that the authentication parameters in the URL are complete, and confirm whether your service provider generated a new address.
• HTTP 403: The server refused the request, possibly because of access restrictions or the status of your credentials. Don’t assume the subscription has expired; ask your service provider to check why the request was refused.
• HTTP 404: The requested path wasn’t found. Check whether you copied an old path or used an account management page URL instead of the subscription URL.
• HTTP 429: Too many requests. Stop refreshing and try again later, following the server’s retry instructions or your service provider’s guidance.
• HTTP 5xx: The server or an upstream service is usually having a problem. Note the status code and time, then try again later. Repeatedly editing local entries generally won’t restore a remote service.

Even an HTTP 200 response may return a login page, verification page, or blank content instead of a subscription the app can parse. If you see a format error or no valid entries after updating, check the response type and ask your service provider whether the subscription output is compatible with Shadowrocket. A webpage opening in a browser doesn’t prove the subscription is valid.

Expired links and invalid formats: check the complete URL

Subscription URLs often contain access credentials. The example https://example.com/sub?token=xxxx is an obviously fake value, not a working service address. Keep the path and all query parameters in the actual URL exactly as provided. Removing anything after the question mark may turn a valid subscription into an unauthenticated request.

1. Check the source: Go back to the subscription information provided by your service provider and make sure you copied the subscription URL—not an account home page, login page, or instructions page.
2. Check that it’s valid: Confirm your subscription status, validity period, and link status. Some services invalidate old links when a new one is generated, so restoring account access may not make the old link work again.
3. Check that the URL was copied in full: Preserve the original encoding and every parameter. Don’t replace characters such as %, &, or =, and don’t treat a shortened display of the URL as the complete address.
4. Check the output format: Use the format your service provider identifies as compatible with Shadowrocket. The subscription container’s encoding and the protocols used by its entries are separate layers. Seeing a protocol name in the text doesn’t prove the full content is valid.
5. Test once after editing: Update the URL for the existing subscription, then manually refresh once. Keeping the original group makes it easier to compare results and avoids confusion between old and newly imported entries.

Names such as Shadowsocks, VMess, VLESS, and Trojan describe the protocol used by an entry. A subscription URL returns a set of configurations. A single share link is different from a refreshable subscription source; putting one in the Subscribe URL field won’t enable remote list updates.

Treat subscription credentials as sensitive information

When contacting your service provider, share the error message, time, and a URL with credentials redacted. Don’t disclose the full subscription link, authentication parameters, or screenshots containing them. If you suspect a link has been exposed, ask your service provider to generate new credentials.

Update succeeds but entries don’t work: check the connection and routing

Subscription refreshes and connections may use different network paths. If you still can’t access a destination after a successful update, first make sure the selected entry is present in the updated list, then check the connection status and Global Routing instead of repeatedly refreshing the same subscription. Repeated updates add requests but can’t fix rule matching.

• Check the entry: Compare its name, server address, and port with the information from your service provider. Similar names don’t necessarily mean two entries have the same authentication details.
• Check the connection: Check the app’s connection switch and the system VPN status. If needed, save your current work, then reconnect so the new connection uses the updated configuration.
• Check the routing mode: Proxy, Direct, Config, and Scene under Global Routing handle traffic in different ways. With Config selected, requests are also governed by the active configuration rules.
• Check the rules: Rules such as DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL affect policy selection; they don’t determine which entries the subscription server returns. Check the active configuration and rule order in Config.
• Distinguish the failures: If one entry fails while others work, check that entry and its server. If all entries fail but the subscription updates, continue by checking connection permissions, the network, and configuration. Don’t mistake these for a single subscription update failure.

After maintenance, run one more manual update to confirm the target group still refreshes normally, and check whether Update on Open suits your routine. If you need to report an issue, include how you triggered the update, the exact error, network type, and checks you’ve already done. Don’t disclose subscription credentials.