This guide is for users who already have a subscription URL from their own provider. First, manually update the subscription in Home, then check Settings → Subscribe for the option to update when the app opens. If an update fails, narrow down the cause by checking the link, network, and response content. After updating, test server connectivity separately: a successful subscription refresh does not mean the connection is working.
What a subscription update changes
A Shadowrocket subscription update requests the saved subscription URL again and parses the returned server configuration. It does not update the app or refresh rule files in Config. This guide covers managing a subscription you already have; it does not provide, sell, or recommend subscriptions or related services.
An update may add servers, remove old entries, or change addresses, ports, and connection parameters. Later refreshes may reload remote settings and overwrite manual changes to a subscription entry, so record important adjustments first. If the previously selected entry is removed, check your selection in Home again instead of relying on the total entry count.
Bottom line: identify what you need to update
To update the server list, update the subscription in Home. To change how DOMAIN-SUFFIX, GEOIP, IP-CIDR, or FINAL rules match, check the active configuration in Config. Repeatedly refreshing a server subscription will not fix rule order.
Manually update a subscription in Home
Manually update the intended subscription after importing it for the first time, when your provider says its configuration has changed, or when an automatic update’s result is unclear. If you have multiple subscriptions, update each one separately and note the result so a success message for one group is not mistaken for a successful update to another.
-
Identify the group
Open Home and find the subscription group you want to refresh. Check its label and entries to confirm it is an imported subscription, not a server you added manually.
-
Check the URL
Open the subscription’s edit details and make sure the URL is complete. To add it again, go to Home → + → Type → Subscribe, enter your own subscription URL, and save. When troubleshooting, keep the original entry at first rather than deleting it.
-
Run the update
In Home, swipe left on the subscription group’s title row and select Update. Make sure you act on the subscription row, not an individual server within the group; they have different actions. Wait for the request to finish rather than triggering repeated refreshes.
-
Check the result
Look for an error message and check whether the expected addresses, ports, or entries have changed. An unchanged list does not necessarily mean the update failed: the remote content may be identical to what was already saved.
-
Test the connection
In Home, confirm the selected server again, then run Connectivity Test. To test an actual connection, make sure the connection switch is on and system VPN permission is granted. A completed subscription request does not establish a data connection.
Set up automatic updates when the app opens
Go to Settings → Subscribe and find Update on Open, which controls subscription updates when the app opens. Turn it on if needed. Labels and layout may vary by installed version. After enabling it, return to Home and check what happens the next time you open the app; the switch position alone does not confirm that an update ran.
Update on Open is a trigger, not a scheduled background task. It does not keep refreshing while the app is closed, nor does it guarantee an immediate request every time the app moves between the foreground and background. A reachable network, valid URL, and parseable response are still required for an update to succeed.
- Check the current setting: Confirm whether the option is enabled on your own device rather than assuming its default based on another device.
- Test manually first: Confirm that Update works manually before checking the automatic trigger. This avoids troubleshooting multiple variables at once.
- Allow time for the request: Wait for the request to finish after opening the app. The list shown immediately in Home may still be the previously saved content.
- Do not confuse it with automatic connection: Settings → On Demand controls when a VPN connection is established. It does not schedule subscription updates. Do not change On Demand as a first step when troubleshooting automatic refreshes.
If you are still unsure whether an update ran, ask your provider to confirm that the remote configuration contains a recognizable change, then check Home. An unchanged count does not prove that automatic updating did not run; a larger count does not prove that every entry can connect.
Update timed out: check how the request is routed
Whether a subscription URL is reachable and whether a server in the list can connect are two separate things. The subscription domain may be unreachable over a direct connection but accessible through an existing connection. Conversely, if the currently selected server is down, a subscription request routed through it may fail.
| Check | Where to check | How to assess it |
|---|---|---|
| Current network | The device’s Wi-Fi or cellular settings | Switch networks and update the same subscription. If the result changes, investigate the network path further. |
| Existing connection | Home → Connectivity Test | Test the current server first; you cannot rely on a failed connection to retrieve replacement settings. |
| Update through a proxy | Settings → Subscribe → Update via Proxy | If an existing connection works but a direct request fails, enable this option and retry, then compare the results. |
| Routing mode | Home → Global Routing | Note whether the current mode is Config, Proxy, Direct, or Scene. Avoid changing routing and refresh settings at the same time. |
Update via Proxy is not a universal fix. Before enabling it, select a working server and establish a connection. If the subscription URL is only reachable directly, test again with this option off. Under Global Routing, Proxy routes through a proxy, Direct connects directly, Config follows the configuration, and Scene follows the selected scene. None of these settings means that automatic updates are enabled.
Change one setting at a time: note its original value, refresh manually once, and record the result before moving on. Do not change the network, server, and multiple switches at once; otherwise, even if updating starts working, you will not know which change made the difference.
Identify the cause from the error message
The examples below are error messages that may appear at the network or HTTP response level. The wording and display language may vary, so record the complete message shown on your device rather than expecting the exact same text every time. “Update failed” alone is not enough to tell whether the URL is invalid or the connection was interrupted.
Error: The request timed out.
Cause and fix: The request did not finish before the timeout. Network issues, DNS, or the remote server may be responsible. Try switching between Wi-Fi and cellular. If you have a working connection, compare the results with Settings → Subscribe → Update via Proxy on and off. A timeout alone does not mean the subscription has expired.
Error: A server with the specified hostname could not be found.
Cause and fix: The subscription domain could not be resolved. Check that the hostname in the URL is complete and contains no spaces or extra punctuation, then try another network. If it still fails, ask your provider whether the domain is still in use.
Error: HTTP 401 Unauthorized
Cause and fix: The server requires valid authorization. Make sure you copied the complete current subscription URL, not the address of a sign-in page. If the authorization parameters were reset, retrieve the URL from your own account and update the saved value.
Error: HTTP 403 Forbidden
Cause and fix: The server rejected the request, possibly because of authorization, access restrictions, or account status. Check the complete URL first, then give your provider the status code and the conditions under which it occurred. Do not assume that a 403 means you need to change protocols.
Error: HTTP 404 Not Found
Cause and fix: The requested path does not point to a resource. Check whether the path was truncated or query parameters were omitted, and confirm that the subscription endpoint has not changed. Repeatedly refreshing the same invalid URL usually will not change the result.
For certificate-related errors, check the device’s date and time, the subscription domain, and whether the current network is intercepting requests with a sign-in page. Ask your provider to check the certificate as well. Do not hide the problem by bypassing security checks. If a public network requires sign-in, complete it in the system settings before retrying in the app.
Why can’t the response be parsed if the URL opens?
A successful HTTP request does not guarantee that the response is a usable subscription. The server may return an account sign-in page, an expiration notice, or a network verification page. Even if the page loads normally, it is not a server list that Shadowrocket can import.
The addresses below illustrate URL structure only; they are not usable subscriptions. Query parameters in a real URL are part of its credentials. Keep them intact when copying, and never share them in public groups or paste them into an untrusted conversion site.
https://example.com/sub?token=xxxx- Copy the right address: Use the subscription URL from your own account. Do not copy the account portal URL or use the image address of a QR code as the subscription content.
- Keep all parameters: Preserve the parameters after the question mark, including separators such as
&. Messaging apps may wrap long URLs, and manually editing them can invalidate authorization. - Check the response type: If the response is an HTML sign-in page, notice, or empty result, resolve the access or account issue first. Changing Global Routing cannot turn a web page into a subscription.
- Check format compatibility: Ask your provider to confirm that the output uses a subscription format Shadowrocket can recognize, rather than another configuration structure or a standalone rule file.
- Only some entries fail: Check whether the relevant protocol fields are complete. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard require different parameters; changing Type at random is not a substitute for fixing the original configuration.
Verify the update and troubleshoot common questions
After refreshing, check the group, selected server, Connectivity Test, and actual access in that order. If the result is caused by a rule, check Config. If server authentication or transport fails, review that entry’s parameters. Separating these layers helps prevent connection problems from being mistaken for subscription problems.
The subscription updated successfully. Why is the server count unchanged?
The remote configuration may have changed only an address, port, or authentication parameter, or it may not have changed at all. Check the entries you expected to change instead of comparing only the count. If you are still unsure, ask your provider what the URL currently returns.
Do I still need to refresh manually after enabling automatic updates?
Yes, when troubleshooting. Select the subscription in Home and run Update to confirm that the URL and network work, then check Update on Open in Settings → Subscribe. This helps distinguish a failed request from an unmet automatic trigger.
What should I do if the selected server disappears after a refresh?
First, make sure you are looking in the correct subscription group. Select another entry retained by the latest update and run Connectivity Test. Do not assume the previous selection will remain valid after the remote entry is removed or renamed.
Do I need to send someone my full subscription URL for troubleshooting?
Usually, the complete error message, network type, manual update result, and Update via Proxy status are enough to start. Hide the URL’s path credentials, query parameters, password, and account details. If the full URL has been exposed, reset it in your own account and save the new one.
For further help with connection settings, see the settings guide. Shadowrocket is a closed-source commercial app for Apple platforms, primarily used on iPhone and iPad. The App Store is the only place to get it. A one-time purchase of the app does not include a service plan; check the App Store listing for the price, system requirements, and purchase eligibility.