This guide is for Shadowrocket users who already have a subscription from their own provider. First, refresh it manually from Home and check the results. Then go to Settings → Subscribe to enable Update on Open. If a request fails, check your network, update route, and subscription URL in that order. Updating a subscription fetches the list returned by your provider; it does not renew your service, change Global Routing, or update rules in Config.
What a subscription update changes: the server list, not rules or your plan
After you save a subscription URL in Shadowrocket, the app requests its contents and adds any recognized server entries to Home. If your provider changes an address, port, authentication details, or server name, your existing entries won't update just because the connection toggle is on. Fetch the subscription again to get the latest content. Whether new entries appear depends on what your provider returns.
First, confirm that the entries come from a subscription rather than being added one by one. If you only entered server details and have no subscription URL, pull-to-refresh cannot fetch a new list. To add a subscription for the first time, tap “+” in the top-right corner of Home → Type → Subscribe, enter your own subscription URL, and save. You don't need to add an imported subscription again each time you update it.
- Subscription list: Returned by the subscription URL. An update may add, remove, or change entries; the total count may stay the same.
- Config: Used for configuration files and rules. Updating a server subscription does not update configuration files managed separately in Config.
- Global Routing: Determines whether connections use Config, Proxy, Direct, or another routing mode. It does not control how often subscriptions update.
- Service validity: Managed by your provider. Refreshing repeatedly won't extend your plan or add more usage.
Manually update from Home: refresh, then check the results
Manual updates are useful for verifying a newly imported subscription, syncing changes announced by your provider, or troubleshooting a failed automatic update. Before you start, make sure your device can access the internet. If Home has multiple subscription groups, note the name of the group you want to update so you don't mistake changes in another group for the result.
-
Find the subscription
Go to Home and locate the subscription group you want to update. Confirm that it uses a subscription URL from your existing provider, not the connection details for an individual server.
-
Pull to refresh
Pull down on the list in Home to refresh the subscription. If you have multiple groups, check the update result for each one. A successful result for one group doesn't mean all groups updated successfully.
-
Wait for the result
Wait for the refresh to finish and note any timeout, parsing error, or other message. Don't pull to refresh repeatedly while a request is still in progress, or change the subscription URL mid-request.
-
Check the entries
Expand the target group and check whether the new names or entries announced by your provider appear. If the selected server was removed, choose an available entry that remains in the list.
-
Test the connection
Test the connection with the site or service you need to access. Record whether the update succeeded and whether the selected server works as two separate results.
For example, having 12 entries both before and after an update doesn't mean nothing changed: a server address may have changed while its name and the total count stayed the same. Conversely, a new name doesn't guarantee that every server can connect. Judge the result by the refresh feedback, expected changes, and connection test—not just the list length.
Enable Update on Open: Settings → Subscribe
To reduce manual refreshes, go to Settings → Subscribe and enable Update on Open. The next time you open Shadowrocket, check the update feedback on Home. After setting up a subscription for the first time, it's still a good idea to refresh it manually once to confirm the URL works over your current network route.
“On Open” means the update is triggered when the app opens. It does not mean the app polls in the background at fixed intervals or will always fetch a new list while in the background. System scheduling, network conditions, and whether the app is already handling a request can all affect when the update completes. Don't treat this setting as a service-expiration reminder or a connection keep-alive option.
Two ways to update: choose based on what you need
Manual update
- Where: Pull down on the list in Home.
- Best for: Initial checks, provider change notices, and troubleshooting.
- Benefit: See request feedback and list changes in the same operation.
- Tip: Change one related setting at a time, then refresh to check the result.
Update on Open
- Where: Settings → Subscribe → Update on Open.
- Best for: Subscriptions you've verified and want to sync when opening the app.
- Requirement: The subscription URL must be reachable when the app opens.
- Note: Opening the app does not guarantee that the request will succeed.
First verify the subscription with a manual update, then enable Update on Open. You can use both methods together; there's no need to repeatedly delete and reimport the subscription.
If an automatic update doesn't fetch a new list, first try a manual refresh on the same network. If that fails too, troubleshoot the network or URL. If manual refresh works but Update on Open doesn't, check that the setting is enabled and that the same network conditions are available when the app opens.
Update via Proxy vs. On Demand
Some subscription URLs aren't directly accessible on your current network but work over an existing connection. In that case, check Update via Proxy in Settings → Subscribe. This setting controls whether subscription requests go through a proxy. It won't fix an expired token or make an unavailable server work again.
Subscription request route
- Where
- Settings → Subscribe
- Setting
- Update via Proxy
- Purpose
- Send subscription update requests through a proxy.
- Requirement
- An available server and an established connection using the relevant route.
After changing this setting, return to Home and refresh manually to compare the results. A timeout doesn't necessarily mean you need to enable it.
Automatic connection conditions
- Where
- Settings → On Demand
- Purpose
- Start or stop a VPN connection based on configured network conditions.
- How it relates to updates
- Affects whether a connection is available; it doesn't replace subscription refresh.
- How to check
- Check the current connection status first, then verify the update from Home.
On Demand and Update on Open are separate settings: one handles connection conditions, the other syncs subscriptions when the app opens.
Keep conditions comparable while troubleshooting. Refresh once on your current network and note the error. If an existing server connects successfully, establish the connection, check Update via Proxy, and try again. Don't change networks, Global Routing, and multiple subscription settings at once; otherwise, even if the update succeeds, it will be hard to tell what made the difference.
Update failed: check each symptom
Keep the existing subscription; don't start by deleting and re-adding it. Re-adding the same unavailable URL will usually produce the same result and may lose group and selection details that help you compare. Note the error message, network, whether Update via Proxy is enabled, and whether the problem affects only one subscription group. These details can help identify the cause.
Pull-to-refresh keeps timing out. What should I change first?
First, make sure you've completed any Wi-Fi network sign-in or authentication, then try again from Home. If other internet access works but the subscription request times out, compare the result on another network you can use. If an existing proxy connection works, check Settings → Subscribe → Update via Proxy. Change one condition at a time and record the result.
Why does changing networks not fix a parsing error?
A parsing error can mean the URL returned a login page, an error message, or unsupported content instead of a valid subscription. Go back to your original provider's subscription management page and copy the full URL again. Make sure it's not a plan information page or individual server details. If the error continues, send the error text to your provider and ask them to confirm the response format.
It updated yesterday, but today says access is denied. What should I do?
Check the validity of your account with the original provider and whether the subscription token was reset. If the request reports HTTP 401 or 403, first check authorization and service status. A 403 can also result from server-side access restrictions, so the status code alone doesn't prove that your plan has expired. If you get a new URL, update the target subscription and refresh.
The update succeeded, but why does the list look the same?
First check the target subscription group, then confirm that your provider actually published changes. The same name can refer to updated connection details; if the returned content hasn't changed, an unchanged list is expected. Don't repeat requests just to make the entry count change.
The list is empty after updating. Should I delete the subscription right away?
First check whether the group is expanded and whether a search filter is active. Then check for a parsing error during the refresh. If the URL is complete and the service is valid but the list is still empty, ask your original provider to verify the content returned for your account. Keep the URL and error details, and don't repeatedly delete all your configurations before you know the cause.
Subscription URLs often look like https://example.com/sub?token=xxxx; this is only a nonfunctional example. Use the exact path, parameter names, and characters provided by your own service provider. When copying, don't include line breaks, spaces, or chat text, and don't remove parameters after the question mark. Separators such as & may also matter, so copy the entire URL.
After updating: check list sync and connection availability separately
A successful subscription request only means the app retrieved and processed the response. Server reachability, valid authentication details, and the expected Global Routing mode are separate connection checks. If the list updated but access still fails, refreshing it repeatedly usually won't fix a rules or connection issue.
- Check your selection: Return to Home and confirm that the selected server is still in the updated group. If the entry was removed, select another one.
- Check the mode: For rule-based routing, confirm that Global Routing is set to Config and check the configuration currently in use. Proxy and Direct handle traffic differently; don't treat them as the same test condition.
- Check the rules: Rules in Config, such as DOMAIN-SUFFIX, IP-CIDR, and GEOIP, and the FINAL fallback are part of your rule configuration. Refreshing a server subscription won't update them automatically.
- Check the credentials: If only one server fails, test it separately from other entries in the same group. This helps distinguish a single connection failure from a subscription update problem.
- Check automatic updates: Once manual refresh works, leave Update on Open enabled and check the result the next time you open the app. There's no need to repeatedly quit and reopen the app to trigger requests.
Use a consistent routine: when your provider announces a change, refresh manually from Home, check for the expected entries, confirm your selection, and test access. Update on Open can keep the list in sync between manual checks. If an update fails, identify whether the problem is the request, content parsing, or the connection, then address that step.