This guide is for users who already have a subscription URL from their own service provider. First, pull down on Home to refresh manually, then check Settings → Subscribe → Update on Open. If an update fails, check the link, network request, and response format in that order. After a successful refresh, verify the server list, selected server, and connection separately—a refresh animation alone does not confirm success.
What a subscription update changes
A Subscribe entry in Shadowrocket stores a subscription URL. When you refresh it, the app requests that URL, reads the server data returned by the provider, and updates the associated group. This does not update the app itself or renew your service plan. The steps below use the iPhone / iPad interface; on other platforms, look for the corresponding options in the interface.
The server list in Home, rule configurations in Config, and app preferences in Settings are separate layers. A successful subscription update usually means that the server data was fetched and parsed; it does not mean that a rule file in Config was also updated. Servers added individually are not automatically included in a subscription when another subscription refreshes.
Manually refresh from Home
Start troubleshooting with a manual refresh. It gives you a clear trigger time and makes it easier to match any on-screen error to that request. Don’t delete the entire group after the first failure. Keep the existing entry and error details so you don’t also lose track of the server currently in use.
-
Check the subscription entry
Go to Home and find the Subscribe entry you want to update. Open its edit screen, confirm that Type is set to Subscribe, and check that the URL matches the current address from your service provider.
-
Add an entry if needed
If you have only manually added servers and no subscription entry, tap “+” in the upper-right corner of Home, set Type to Subscribe, paste your subscription URL into URL, and save. Skip this step if you already have an entry.
-
Pull down to refresh
Return to Home, pull down from the top of the list, and release. Wait for the refresh to finish. If you have multiple subscriptions, check each one separately; success for one does not mean they all updated.
-
Check the results
Review the server names and entries under the target subscription. An unchanged list may mean the remote content hasn’t changed. If an error appears, note its exact text rather than simply writing “update failed.”
-
Test the connection
Check the dot next to the selected server again, connect if needed, then run Connectivity Test. Fetching the list successfully and connecting to a server are separate results.
Turn on Update on Open
Go to Settings → Subscribe → Update on Open and turn on updates when the app opens. Then open the app normally and check whether the subscription refreshes. Settings may be arranged differently across platforms, so look for the option by name. This setting isn’t in Config.
- Set a manual baseline first: Manually update the subscription once before enabling automatic updates. If a manual request fails, Update on Open won’t fix an invalid URL, access issue, or unsupported format.
- Know when it runs: Update on Open is for when you open the app. It doesn’t guarantee that the app will refresh at fixed intervals in the background.
- Wait until the network is ready: If you’ve just switched Wi-Fi networks, signed in to a network, or turned off Airplane Mode, confirm that you’re online before opening the app to check.
- Check the actual result: Seeing the old server names after opening the app doesn’t by itself mean the setting failed. The remote list may be unchanged; check for errors and compare with a manual refresh.
Settings → On Demand controls when connections start based on conditions; it does not schedule subscription updates. Don’t keep changing On Demand to make subscriptions refresh automatically. If manual updates work but Update on Open doesn’t, first confirm that Update on Open is still enabled, then note the network status when you open the app.
Read the exact error before choosing what to try
“Update failed” can point to problems at different stages. The cards below show common error messages and HTTP status codes. The exact wording may depend on the system and server, so use the complete message shown on screen rather than assuming every failure means the link has expired.
Error: Failed to load subscription
What it means and what to do: This is a general subscription loading error; it doesn’t confirm whether the link expired or the format is invalid. Check the full URL, then look for a more specific network or HTTP error from the same request.
Error: The request timed out.
What it means and what to do: The request didn’t finish in time. The cause may be your local network, the remote server, or the request route. First check that you can access the internet, then try the same URL once on Wi-Fi and once on cellular data.
Response status: HTTP 401
What it means and what to do: The server requires valid credentials. The token in the URL may be missing, expired, or reset. Get the current subscription URL from your service provider, replace the entire URL, and try again.
Response status: HTTP 403
What it means and what to do: The server refused the request, possibly because of account permissions or access policies. Send your service provider the status code and time of the error; this status alone doesn’t prove that your plan has expired.
Response status: HTTP 429
What it means and what to do: The server is limiting requests because they’re coming too often. Stop refreshing repeatedly and wait as your service provider advises. If the response includes Retry-After, follow that instruction.
Change one thing at a time while troubleshooting. For example, keep the subscription URL unchanged and switch networks first. On the next attempt, keep the network the same and try a new URL from your service provider. Otherwise, even if the update works, you won’t know which change fixed it.
Expired links, network errors, and unsupported formats
Check the link: verify the full URL and account status
The token in a subscription URL is usually used for authentication. Leaving out parameters after the question mark, or adding an extra space or line break, can make a request fail. If your service provider reset the link, the old URL may stop working immediately. Confirm that the link is still valid and that your account can access the subscription.
- Compare the scheme, domain, path, and query parameters—not just the domain.
- If the link redirects to a login page, ask your service provider whether they gave you a subscription URL or an account management page.
- Replace the URL in the existing entry and save it before testing. Avoid adding multiple groups with the same name, which can make the results confusing.
Check network reachability: distinguish DNS, connection, and certificate errors
An HTTPS subscription URL without an explicit port usually connects over TCP 443. DNS lookup failures, connection timeouts, and TLS certificate validation errors are different problems. Being able to open other websites only confirms that some network access works; it doesn’t prove that the subscription domain is reachable.
- DNS lookup failure: Check the domain spelling and try again on another local network. Don’t rewrite all your DNS settings because one subscription failed.
- Connection timeout: Keep the URL unchanged and compare results on Wi-Fi and cellular data. Note whether the issue occurs only while VPN is connected.
- Certificate error: Check the device’s date and time, and ask your service provider to verify the certificate. Don’t hide the problem by disabling certificate validation.
Proxy, Direct, Config, and Scene under Home → Global Routing affect how connections and traffic routing work, but don’t assume they determine the route used for every subscription request. Switching between Proxy and Direct also changes the traffic path for other apps. Note the current mode and VPN status while troubleshooting; don’t leave the app in a different mode just to refresh a subscription.
Unsupported formats: a successful response may still be unusable
An HTTP 200 response means the HTTP request succeeded, but it doesn’t guarantee that the response body is a valid subscription. The server may return a login page, maintenance notice, or empty body. Even recognized subscription data may not produce usable entries if required fields are missing or protocol parameters are incomplete.
| What you see | Check first | Next step |
|---|---|---|
| The response is an HTML page | Was a login or verification page returned? | Ask your service provider for the subscription URL to use with Shadowrocket |
| The response or server list is empty | Has the account been assigned server data? | Ask your service provider to check the response; don’t delete the existing group |
| Some entries won’t import | Are the required fields for that protocol complete? | Send a redacted error and the protocol type; don’t guess at the parameters |
| Names and server count haven’t changed | Has the remote list actually been updated? | Confirm the request succeeded, then ask your service provider about the expected content |
If the update succeeds but you still can’t connect
A successful update doesn’t mean every server is reachable. If the remote list removed or replaced an entry, check the selected server again. For VMess, VLESS, Trojan, and other entries, the address, port, UUID or password, transport, and TLS settings must come from your service provider. Don’t fill in values at random to clear an error.
- In Home, confirm that the selected server is the updated entry—not a manually added entry with the same name.
- Connect, then run Connectivity Test to tell whether the subscription can be fetched and the server can be reached.
- If the test succeeds but a particular domain still has a problem, check the current Global Routing mode and which Config rules match.
- When checking rules such as DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL, change only settings related to the issue. Editing rules won’t fix an unsupported subscription format.
When contacting your service provider, include the time of the error, the local network you used, the exact error message, and the results of manual and on-open updates. Redact tokens, UUIDs, and passwords from subscription URLs. Don’t share a full URL in public screenshots or comments. If it has already been exposed, reset the link with your service provider and update the URL in the app.