If you already have a provider and subscription, start by refreshing manually from Home, then check Settings → Subscribe for Update on Open. If an update fails, check the link’s authorization, the network used for the request, and the response content in turn. If the update succeeds but you can’t connect, check connection parameters and routing instead—these are separate issues.
What a subscription update does: fetches a list, not a connection
A Shadowrocket subscription update uses a saved subscription URL to request content from a server, then parses the server entries it contains. Manual refresh is useful for checking the result after the first import, confirming changes announced by your provider, or investigating a specific failure. Update on Open checks for list changes when you open the app during normal use.
A successful update only means the request returned content that could be processed. It doesn’t confirm that every server can connect or that your remaining account traffic, server certificates, and remote ports are all in order. Likewise, a saved entry that still connects doesn’t prove the subscription URL is valid: subscription authorization and connection credentials may be managed separately.
- Home: View subscription groups, the server list, and the current selection, or refresh manually.
- Settings → Subscribe: Check subscription update options, including Update on Open and Update via Proxy.
- Config: Manage configuration files and their rules. Refreshing a server subscription does not update a remote configuration file.
- Connection toggle: Controls the connection state; it doesn’t indicate whether a subscription update succeeded.
Manual refresh: confirm the group, then check the results
When importing for the first time, copy the complete subscription URL provided by your provider—not an account sign-in page, payment page, or individual server share link. Query parameters at the end of the URL often contain authorization details, so don’t remove them just because the URL is long. The example below uses a dummy value to show the URL structure and cannot be used to connect:
https://example.com/sub?token=xxxx-
Verify the source
Copy the subscription URL from your provider’s account page. Keep the scheme, path, and query parameters intact, and check that no spaces, line breaks, or punctuation from a chat message were added at either end.
-
Save the subscription
To add a subscription for the first time, go to Home → tap “+” in the upper-right corner → Type → Subscribe, paste the full URL, and save. If you already have a subscription, use its existing group; there’s no need to add it again.
-
Pull to refresh
Return to Home and pull down on the list to refresh. Wait for the request to finish. While troubleshooting, avoid repeated refreshes so you can tell which result belongs to which request.
-
Check the contents
Expand the target subscription group and check the entry names, count, and expected changes. If the list hasn’t changed, first confirm that the server has actually published new content before continuing to troubleshoot.
A single pull-to-refresh may update multiple saved subscriptions. A failure in one group doesn’t mean the others failed; note the specific group and message. An unchanged item count doesn’t necessarily mean there was no update: the server may change addresses, ports, or connection parameters without changing names or the number of entries.
Don’t repeatedly delete and re-add subscriptions to test a refresh. Doing so removes the before-and-after comparison and can create duplicate group names. Keep the existing entries until you’ve confirmed that the new subscription URL parses correctly, then decide what to do with the old group.
Update on Open: where to enable it and when it runs
Go to Settings → Subscribe and enable Update on Open. This option triggers a subscription update when you open the app; it isn’t a scheduled background poll. After enabling it, check the result of an actual request rather than assuming the list has updated because the switch is on.
- Test manually first: Confirm that pull-to-refresh succeeds on Home before enabling automatic updates. This helps rule out an invalid URL as the cause of an apparent trigger issue.
- Then check the trigger: The next time you open the app, wait for the request to finish and check the target group’s contents and any failure messages.
- Keep the manual option: If your provider announces list changes, you can refresh manually instead of waiting until you next open the app.
- Distinguish connection behavior: Settings → On Demand manages on-demand connections, not subscription updates. Opening the app also doesn’t necessarily establish a proxy connection.
If automatic updating fails but a manual refresh succeeds later, compare the network conditions for the two requests. For example, Wi-Fi may not have finished its sign-in process when you open the app, or a proxy connection may not yet be established. Reproduce the difference first, then adjust settings one at a time to pinpoint the cause.
Subscription update failed: distinguish authorization, network, and content issues
First, note the exact message, when it occurred, and which network you were using. The examples below can help narrow down the issue, but the wording and details shown may vary. An HTTP status may appear only in the server response or diagnostic records. Don’t assume a subscription has expired based only on a generic loading error.
Failed to load subscription
What it means and what to do: This is a general loading failure and doesn’t identify whether the cause is authorization, the network, or the response format. Check the full URL first, then look for a timeout, HTTP status, or parsing message.
The request timed out.
What it means and what to do: The request didn’t finish within the allowed time. The current network, route, or server response may be responsible. Retry on another available network, then check whether Update via Proxy is relevant.
401 Unauthorized
What it means and what to do: The server didn’t accept the authorization for this request. Copy the current subscription URL from your own account page and check whether the token is missing, expired, or has been reset.
403 Forbidden
What it means and what to do: The server denied access, possibly because of account permissions or access restrictions. Ask your provider to confirm the applicable limits; repeatedly refreshing won’t remove an access restriction.
404 Not Found
What it means and what to do: The requested path didn’t match a resource. Check whether the address was truncated or the path has changed, and get the subscription URL again from your account page.
An HTTP status can help narrow down the issue, but it can’t replace checking your account. For example, an invalid link may return an error status or a help page with a 200 status. In the latter case, the network request completed, but the response still can’t be used as a subscription.
- Invalid link: Check that the URL shown in your account matches the one saved in the app. If authorization was reset, you’ll usually need to replace the old URL.
- Network restrictions: Check whether your current Wi-Fi requires you to sign in through a web page. On iPhone, you can compare by switching to cellular data; keep data charges in mind.
- Unsupported response format: Confirm that the response contains subscription data the app can recognize, not a sign-in page, web verification page, JSON error message, or empty response.
- Temporary server issue: Note the time and error message, try again later, and contact your provider. Avoid sending repeated requests in a short period.
Update via Proxy: test only when you already have a working connection
Settings → Subscribe → Update via Proxy changes the route used for subscription requests. It won’t fix an invalid token or convert a subscription to another format. Use it for comparison only when the current network can’t reach the subscription domain directly but an existing entry can establish a working proxy connection.
| What you observe | Next step | How to interpret the result |
|---|---|---|
| Updates work directly on the current network | Keep the verified settings and check automatic updates | No need to change the request route for troubleshooting |
| Direct request times out, but an existing proxy works | Establish a connection, enable Update via Proxy, then refresh manually | If only this route succeeds, check network reachability to the subscription domain |
| Both routes return 401 or 403 | Stop retrying; check authorization and access restrictions | Changing the route can’t grant access the server hasn’t authorized |
| No usable connection entries | First test another available network and contact your provider | A proxy that hasn’t been established can’t fetch the subscription for the first time |
Bottom line: change one condition at a time
Keep the same subscription URL. Compare networks first, then compare Update via Proxy, and record each message. If you change the URL, switch networks, and replace the configuration at the same time, you won’t know which change resolved the issue.
Also check the current option under Home → Global Routing. Direct uses a direct connection, while Proxy, Config, and Scene each serve different purposes. Turning on the connection toggle doesn’t mean every request will necessarily use a proxy. When troubleshooting, consider the selected routing mode, configuration, and available connections; don’t rewrite the entire Config just to refresh a subscription.
Format and connection checks: what to verify after an update succeeds
A subscription URL must return content Shadowrocket can recognize. A provider sign-in page or a temporary page that requires a browser session isn’t a valid subscription address—even if a browser can display text, that doesn’t mean the app can parse its server details. Ask your provider for a subscription output that works with Shadowrocket instead of guessing the encoding or editing the content yourself.
- A web page isn’t a server list: If the response contains
<!DOCTYPE html>, a sign-in form, or web verification instructions, check the URL and access requirements first. - A successful status doesn’t guarantee the right format:
HTTP 200describes the HTTP request result; it doesn’t confirm that the response body uses a supported subscription format. - Protocol parameters must be complete: Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard require different fields. An entry’s name or address alone isn’t enough to confirm it’s complete.
- Check the port against the original value: If your provider specifies remote port
443, compare it with the value saved for that entry. Don’t change every entry to443as a one-size-fits-all fix.
If the list updates successfully but a connection test fails, check your account status, server reachability, authentication details, TLS, and transport parameters instead. Refreshing the same content again usually won’t change the result. In Config, DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL handle rule matching; they can’t fix a subscription response in the wrong format.
FAQ: automatic updates, list changes, and what to do after a failure
The list didn’t change when I opened the app. Did the update run?
Check Update on Open under Settings → Subscribe, then try a manual refresh on Home. If the server content hasn’t changed, the list may look the same even after a successful update. Check the request message and the specific changes announced by your provider.
Should I delete the original subscription after an update fails?
Don’t delete it yet. Note the original group and error, verify the current URL and account authorization, then check the network and response format. Deleting the subscription won’t restore expired authorization and may remove a useful comparison with entries that still work.
Why does the update fail if the link opens in a browser?
Check whether the browser shows subscription data or a sign-in or verification page. The browser may have an active sign-in session that isn’t available to the app, so a page loading successfully doesn’t mean the subscription can be parsed.
Does enabling On Demand automatically refresh subscriptions?
No. This option doesn’t schedule subscription updates. Settings → On Demand manages on-demand connections; set Update on Open under Settings → Subscribe → Update on Open, or pull down to refresh on Home when you need an update right away.
Some entries disappeared after refreshing. Do I need to reinstall?
Ask your provider whether those entries were removed or renamed in the returned list, then make sure you’re viewing the correct group. Reinstalling won’t restore content removed by the server; save any personal configuration notes you need before making changes.