If you already have your own subscription, refresh it manually in Home and confirm the list is current. Then go to Settings → Subscribe and turn on Update on Open. If an update fails, first check whether the request reached the subscription URL, then whether the response can be parsed. Subscription refreshes, connection tests, and Config updates are separate tasks. This guide covers the process in order: update, verify, and troubleshoot.
What a subscription update does: refreshes the list, not the app
A Shadowrocket subscription update rereads a subscription URL you already have and updates the corresponding group of connection entries in Home. If the remote service changes a name, address, port, or other connection setting, refresh the subscription to see those changes locally. This guide assumes you already have a service provider and subscription of your own.
Two separate conditions must be met: the content must be retrieved, and the entries must be parsed. A successful network request that returns a login page is not a valid subscription. Likewise, an updated list does not mean every connection in it will work. Connection availability also depends on the remote service, authentication settings, and your current network.
- Home: View existing connections and subscription groups, refresh the list, and check the updated entries.
- Settings → Subscribe: Manage subscription behavior, including the option to update when opening the app.
- Config: Manage configuration files. Rule or remote configuration updates are separate from refreshing subscription lists in Home.
- App Store: Get and update the app itself; it does not refresh your subscription content.
Manual refresh: check the URL, then verify the group
When importing for the first time or troubleshooting an update, start with a manual refresh. You can inspect the result immediately instead of waiting for an automatic trigger. Before refreshing, note the target group’s name, its current number of entries, and one connection you plan to verify. Use these details for comparison; there’s no need to record or share subscription credentials.
-
Confirm the subscription type
Go to Home and find the existing subscription group. To add one for the first time, tap “+” in the upper-right corner of Home, then choose Type → Subscribe, enter your own subscription URL, and save. A single shared connection link is not a subscription list that can be refreshed.
-
Check the full URL
Open the subscription’s edit screen and check the URL. Make sure all query parameters are present and that no leading or trailing spaces, line breaks, or explanatory text were copied with it. Check only your own URL, and don’t post the complete address in a public discussion.
-
Pull down to refresh the list
Return to Home, pull down on the list, and release to refresh the subscription. Wait for the operation to finish and check for an error message. If you have multiple subscriptions, check the result for each target group separately.
-
Check the update result
Compare the target group’s name and entry count, and look for any known changes. If a specific connection was changed remotely, open its details and verify the address or port before testing the connection.
The example below shows the structure of a URL and cannot be used to connect. token is a query parameter; actual URLs may use different parameter names or include credentials in the path. Don’t replace fields in your own URL based on this example.
https://example.com/sub?token=xxxxUpdate on Open: configure it in Subscribe
After a manual refresh succeeds, go to Settings → Subscribe → Update on Open and turn on updates when opening the app. This setting triggers a subscription fetch when you open the app; it is not a scheduled background task that runs at fixed intervals. Keeping a connection running without opening the app does not mean the subscription has refreshed.
- Test a manual refresh first: If the URL itself is invalid, enabling automatic updates will repeat the same failure. It won’t fix remote credentials.
- Return to Home after enabling: The next time you open the app, check the target group and any entries known to have changed. Don’t assume the update succeeded just because the setting is on.
- Refresh manually when you know something changed: To fetch remote changes right away, refresh the list and verify the result. This is easier to confirm than waiting until the next time you open the app.
- Limit troubleshooting variables: If you’re comparing the results of two refreshes, temporarily turn off automatic updates. Turn it back on after testing if needed.
Update on Open and On Demand serve different purposes. The former controls when subscriptions are fetched; the latter triggers connections on demand. Changing Settings → On Demand won’t fix a subscription URL or replace a list refresh. You don’t need to adjust both settings while troubleshooting a subscription.
| Action or setting | Trigger | What to check |
|---|---|---|
| Pull down to refresh in Home | Manual action | The message for this attempt, the target group, and known entry changes |
| Update on Open | Triggered when opening the app | The actual fetch result, not just whether the setting is on |
| On Demand | Triggered by connection conditions | Connection status; not evidence of a subscription update |
In short: enable automatic updates after a successful manual refresh
First get one repeatable, successful manual refresh, then enable Update on Open. If a problem comes up later, you can tell whether the URL became invalid or the automatic trigger didn’t complete, without changing several settings at once.
Troubleshooting failed updates: check the link, network, and content separately
First, note the full message shown on screen, then check the three causes below. Wording may vary by system language or request stage. An error is a clue, not proof on its own that a subscription has expired.
Error: Failed to load subscription
Cause and solution: This is a general subscription loading error. It may indicate an authorization issue, a failed request, or an unexpected response format. First confirm with your own service provider that the URL is valid, then check network access and the response content separately.
Error: The request timed out.
Cause and solution: The request didn’t complete within the allotted time. The issue may involve your current network, the request path, or the subscription server’s response. Try a manual refresh over both Wi-Fi and cellular, and compare the results.
Error: A server with the specified hostname could not be found.
Cause and solution: The hostname in the subscription URL could not be resolved. Check that the domain was copied in full, then try a different network. If the domain has changed, confirm the current URL with your own service provider.
First: The link is invalid or its authorization has changed
After a provider resets credentials, an old URL may remain in Home but no longer return content. If the request returns HTTP 401 or 403, check authorization and access restrictions first. For 404, check whether the path has changed. These status codes don’t by themselves identify a specific account issue; consider them alongside your own service details.
- Copy the subscription URL again from your own provider’s account page and compare it with the value saved in the app.
- Make sure you copied a subscription URL, not an account homepage, login page, or shared link for a single connection.
- After changing the URL, refresh only the target subscription and check the result. Don’t keep retrying an old URL you’ve confirmed is invalid.
Second: The network can’t reach the server, or the request path is failing
If Wi-Fi fails but cellular works, first investigate what differs between the two network environments instead of rebuilding the subscription. Compare the results after switching networks, then check whether your current connection affects the request. Proxy, Direct, Config, and Scene under Global Routing are routing modes. Changing them may affect network access, but won’t change whether your subscription credentials are valid.
- Change one condition at a time. For example, switch from Wi-Fi to cellular while keeping the subscription URL unchanged.
- If you need to compare results with your current connection on and off, note its original state and restore it after testing.
- Don’t change DNS, routing, and every connection setting at once to fix a single timeout; you won’t know which change made a difference.
Third: The response content can’t be recognized
HTTP 200 means the request received a successful response; it doesn’t guarantee the content is a valid connection list. The server may return a login page, maintenance notice, or other text. A page displaying in a browser doesn’t prove Shadowrocket can parse it as a subscription.
- Confirm that the remote service provides subscription content compatible with Shadowrocket, rather than a webpage that requires a manual login.
- If the request completes but the list is empty, ask your own service provider how many entries and what type of content the URL should currently return.
- Don’t add encoding, remove fields, or replace protocol names throughout the content yourself. Doing so may hide the original issue and break connection settings.
The list looks unchanged after refreshing: verify entry details
A subscription may refresh successfully and still look exactly the same if nothing changed remotely. Conversely, the entry count can stay the same even when the update succeeds, because server addresses, ports, or authentication settings may have changed. To verify an update, check an entry known to have changed rather than relying on the list length.
| What you see | What to check | Next step |
|---|---|---|
| Names and entry count are unchanged | Whether anything actually changed remotely, and whether you’re viewing the right group | Check the details of a connection known to have changed |
| The list changed, but connections fail | Remote availability, authentication settings, and your current network | Troubleshoot the connections instead of repeatedly refreshing the list |
| Only some entries are missing | The number of entries returned, their format, and whether all parameters are present | Ask your own service provider whether the missing entries should still be included |
| The old content is still there after opening the app | Whether Update on Open is enabled and whether the request completed | Refresh manually once and note the message |
For example, if the remote service explicitly says a connection’s port changed from 443 to 8443, check that entry’s port after refreshing rather than just its name. These numbers illustrate how to verify a change; they aren’t recommended ports for any existing connection. Actual settings must match your own configuration.
Before reporting an issue: preserve the details, hide credentials
If the issue persists after these comparisons, prepare a concise troubleshooting report. Include enough detail to distinguish between content that couldn’t be retrieved and content that was retrieved but couldn’t be parsed, while keeping the full subscription URL private. Credentials may appear in the query parameters or the path, so don’t just redact a field named token.
- How it was triggered: Say whether a pull-to-refresh in Home failed or whether nothing changed after enabling Update on Open.
- Network: Record the results over Wi-Fi and cellular, and whether a connection was active during each test.
- Exact message: Copy the full error text and include any HTTP status code.
- Scope: Say whether all subscriptions failed, one group failed, or only some entries are missing.
- Protect your privacy: Hide the full subscription URL, password, UUID, and other authentication fields. Include only the details needed to describe the issue.