This guide is for users who already have their own service provider and subscription URL and need to refresh the server list in Shadowrocket. First refresh manually from Home and check the result, then enable updates on app launch. If an update fails, check the URL, network request, response content, and parsing results in order—subscription update issues and connection issues are not the same.
First, distinguish subscription, app, and configuration updates
A subscription update requests the saved subscription URL again and parses the response into server entries on Home. When your service provider changes server addresses, ports, or authentication details, you need to fetch the updated subscription. Disconnecting and reconnecting the VPN does not fetch it again.
App updates are provided by the App Store and update Shadowrocket itself. Configuration files in Config cover settings such as rules and DNS; updating a remote configuration is a separate operation from refreshing server subscriptions on Home. Before troubleshooting, identify what you need to update.
Manually refresh a subscription from Home
When adding a subscription for the first time, use the subscription URL explicitly provided by your service provider—not an account sign-in page, order page, or webpage sharing link. If you already have a subscription, keep the existing entry. Repeatedly deleting and re-adding it to refresh can erase the previous state you need for comparison.
-
Check the subscription
Open Home, find the subscription group you want to update, and confirm that it belongs to your service provider. If you haven’t added it yet, tap “+” in the upper-right corner of Home to open the add screen. Set Type to Subscribe, enter your subscription URL in URL, and save.
-
Note the current state
Note the number of entries in the target group and the name or port of a known server. Don’t include the full URL, password, or authentication parameters in screenshots; they aren’t needed for public comparisons.
-
Pull to refresh
Return to Home and pull down on the list to refresh the subscription. Wait for the request to finish. If you have multiple subscriptions, check each group separately; success for one group does not mean they all updated successfully.
-
Check the result
Look for an error message, check that the target group still has entries, and verify any changes announced by your service provider. An unchanged entry count does not necessarily mean the update failed: the response may have changed only addresses, ports, or authentication details.
-
Test separately
Select the server you plan to use, then test the connection and access. A successful refresh only confirms that the subscription was fetched and parsed; it doesn’t guarantee that every returned server can connect.
The example below uses a fictional value only to illustrate the structure of a subscription URL. Don’t import it or use it in place of your own URL. Query parameters in real links often provide authentication, so copy the entire URL without adding spaces, line breaks, or non-ASCII punctuation.
https://example.com/sub?token=xxxxEnable updates when the app opens
After a successful manual refresh, go to Settings → Subscribe, find Update On Open, and turn it on. Labels and capitalization may vary by interface language and app version; use the option for updating when the app opens on the current subscription settings screen.
- Before enabling: Manually refresh from Home once to confirm the URL is valid and the current network can request the subscription.
- After enabling: Reopen Shadowrocket, check the subscription request result, and then inspect the target group on Home. Don’t assume the update finished just because the app opened.
- What to expect: Update on open is triggered when the app launches. It does not mean the app will keep refreshing at fixed intervals while closed, nor does it guarantee a new request every time you return to the app.
- If it fails: Return to Home, trigger a manual refresh, and note the error. Automatic updates won’t fix invalid authentication parameters or an unreachable subscription domain.
Pinpoint where the update fails in the request flow
An update involves at least the steps below. Identify where it fails before changing settings; this is usually easier than changing DNS, servers, and configuration files all at once.
| What you see | Check first | Next step |
|---|---|---|
| Immediate 401 or 403 response | Authentication parameters, URL validity, access restrictions | Ask your service provider to confirm the current subscription URL and access requirements |
| Request times out | Current network, domain resolution, server response | Keep the URL unchanged, switch to another available network once, and retry |
| Request succeeds, but the response can’t be parsed | Whether the response is a sign-in page, verification page, or unsupported content | Confirm you copied a subscription URL that the app can import |
| Refresh completes, but entries are unchanged | Whether your service provider actually changed the content | Compare known names, addresses, or ports—not just the entry count |
| Refresh succeeds, but the connection fails | Selected server, authentication details, and connection path | Troubleshoot the connection instead of refreshing the subscription again |
Bottom line: distinguish a failed fetch from a failed connection
If the list parsed successfully, check the selected server and connection logs next. If the subscription response wasn’t received, start with the URL and network. Don’t use the same “update failed” label for problems at two different stages.
Common error messages and what to check
The messages below may appear as raw network request errors or HTTP status codes. Wording can vary by system language, server, and app interface. Record the complete error you actually see rather than just noting that it “doesn’t work.”
HTTP 401 Unauthorized
Cause: The server didn’t accept the authentication details in the request. The token may have expired, a parameter may be missing, or you may have copied an old URL.
Fix: Check your account with your service provider for the current subscription URL. Replace the old URL in full, then refresh manually. Don’t guess or construct authentication parameters yourself.
HTTP 403 Forbidden
Cause: The server rejected the request. This may involve account status, restrictions on the source network, or server-side access policies; the status code alone doesn’t prove that the URL has expired.
Fix: Note when it happened, the current network type, and the status code. Ask your service provider to confirm any access restrictions, and avoid rapid repeated retries.
HTTP 404 Not Found
Cause: The subscription path doesn’t exist. Common causes include a truncated URL, a moved subscription endpoint, or an incorrect path.
Fix: Check the entire URL, including the domain, path, and query parameters. Use the current URL shown in your account, then try updating again.
The request timed out.
Cause: The request didn’t finish within the time limit. The delay may occur while establishing a connection, transferring data, or waiting for the server.
Fix: First confirm that your device is online. Then compare once over Wi-Fi and cellular data. If only one network fails, check that network’s access requirements first.
The link opens, but no usable server entries appear
A webpage opening in a browser only proves that it received some kind of response; it doesn’t prove the response is a subscription. Sign-in, account balance, or access verification pages can return HTTP 200, but their content can’t be used as a server list.
- Check the link source: Copy the link explicitly labeled as a subscription in your account, not the management page URL from your browser’s address bar.
- Check the response content: If the response is an HTML page, sign-in prompt, or error JSON, address the server-side access issue first. Changing the server port won’t fix it.
- Check format compatibility: Ask your service provider to confirm that the link provides a subscription format Shadowrocket can read. Correct encoding and complete protocol fields are separate requirements.
- Check the replacement: If there are still no entries after changing the URL, keep the original group and error record. Don’t delete all existing information before the issue is clear.
Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are protocol names, not switches that convert an ordinary webpage into a subscription. Use the port specified in the response or by your service provider. HTTPS subscription URLs commonly use port 443, but that doesn’t mean every server in the subscription uses 443.
Verify connections and record issues after updating
After updating, first confirm that the selected server on Home is the one you expect, then check Global Routing. Proxy, Direct, Config, and Scene handle traffic differently, and the current mode affects access tests. None of these options refreshes a subscription.
- Check the selection: If your service provider removed or renamed an entry, select one that still exists. Don’t base your assessment on an old selection.
- Check the routing mode: Verify Global Routing against your intended setup. If you use Config, check the active configuration file in Config. A rule may route the test request to DIRECT instead of the selected proxy.
- Test actual access: After connecting, visit a destination you normally use and are permitted to access, then check the connection logs. A successful latency test doesn’t mean every type of request is working.
- Keep a brief record: Note the refresh time, exact error, network type, whether the target group changed, and whether you tested the connection. Change only one condition at a time so you can reproduce the issue.