This guide is for users who have obtained a subscription from their own provider but can’t update it in Shadowrocket or see any servers. First, distinguish a failed request from an unparseable response or a display issue. Then check the URL, account status, and update route one by one. Keep any existing entries that still work, change only one condition at a time, and verify recovery by checking the update result and testing the connection separately.
1. Distinguish an Update Failure, a Parse Error, and an Empty List
Updating a subscription in Shadowrocket is not the same as testing a connection. The app first requests the subscription URL, receives a response, and then parses supported server entries into Home. If any step fails, it may look like no new servers were added, but each failure calls for a different fix.
Go back to Home, expand the relevant subscription group, clear any search text, and check whether the group is collapsed or filtered. Config is mainly for managing configuration files; updating a remote configuration in Config does not update server subscriptions in Home. Use Settings to check options such as update behavior.
| What you see | Check first | Avoid for now |
|---|---|---|
| Times out after waiting for the update | Current network, DNS resolution, and subscription request route | Changing server ports or passwords repeatedly |
| Fails quickly with an HTTP status code | URL permissions, provider account, and API restrictions | Triggering updates repeatedly |
| Request completes, but no usable entries appear | Response content, subscription format, and visible groups | Deleting old entries that still connect |
| Servers appear, but connections fail | Server settings and actual connectivity | Treating a connection issue as a parsing issue |
2. Check the Subscription URL—Don’t Mistake a Web Page for a Subscription
Get the subscription URL from your provider. An account login page, plan details page, individual server share link, and subscription URL are different things. Even if a URL opens in a browser, it may return only a login form or verification page. That does not mean Shadowrocket can parse it as a subscription.
- Copy the Shadowrocket subscription URL again from your provider account. Don’t piece it together from a chat screenshot or text broken across lines.
- Check that it starts with
https://and includes the complete path and query parameters. Remove any spaces, quotation marks, or line breaks before or after the URL, but don’t change characters within it. - Keep
?,&,=, and any existing percent encoding. Don’t remove the entire query string or encode the URL again yourself. - Edit the existing subscription entry in Home, verify its URL, and update that subscription. This avoids importing multiple groups with the same name and confusing the results.
The example below is only to show the structure of a path followed by query parameters; it is a placeholder and cannot be used to connect. Actual URLs may use different parameter names. Don’t assume that token is a required field for every provider.
https://example.com/sub?token=xxxx3. Check the Provider’s Response and Account Status
A complete URL doesn’t guarantee that the provider will return valid entries. An expired account, exhausted quota, invalid access credentials, API maintenance, or too many requests can all affect the response. First check your account with your provider, then decide whether any app settings need to change.
The English text below is standard HTTP response wording; Shadowrocket may not display it verbatim. The app may show only a status code or a shorter error message. Follow the guidance for a status only if you actually see it—an empty list alone doesn’t prove that a specific error occurred.
HTTP 401 Unauthorized
Cause: The request wasn’t authenticated. The subscription credentials may have expired or the required authorization may be missing.
Fix: Get a valid subscription URL from your provider account, replace the old URL in full, and try updating again.
HTTP 403 Forbidden
Cause: The server rejected the request, possibly because of account permissions, access policies, or an authentication check.
Fix: Check your account status and ask your provider whether the subscription endpoint allows the current request. Repeatedly refreshing won’t necessarily remove a restriction.
HTTP 429 Too Many Requests
Cause: The request rate exceeded the API’s limit.
Fix: Stop retrying updates back to back and wait for the interval specified by your provider. If the response includes Retry-After, follow that wait time.
Even a 200 OK response may contain an HTML error page, an empty body, or a format the app can’t recognize. Ask your provider to confirm that it returns subscription content compatible with Shadowrocket—not just that the URL is reachable. Don’t share the full response publicly; it may contain server credentials.
Bottom line: Check the response before changing connection settings
If your provider confirms that the endpoint returns a login page or no entries, resolve the account or subscription URL issue first. Switching Global Routing won’t turn that response into a valid server list.
4. Check the Network and Update Route, Changing One Variable at a Time
Whether a subscription request succeeds and whether an existing server connects are separate outcomes. If your local network can’t reach the subscription domain but an old server still works, check Settings → Subscribe → Update via Proxy and try updating through that proxy. Enabling this option won’t fix invalid credentials or provide a working connection by itself.
- Note whether you’re on Wi-Fi or cellular, whether the connection is enabled, and whether Update via Proxy is on. Keep a record of the original settings so you can restore them.
- First, try a direct update on a trusted network that can access the subscription URL. If you switch between Wi-Fi and cellular, make sure the app has permission to use the relevant network.
- Test a proxy update only if an existing server still works. Verify that the server can access the internet, enable Update via Proxy, then return to Home and update the relevant subscription.
- Record when the update finished, what message appeared, and whether the server count changed. If there’s no improvement, restore the setting before testing the next item. Don’t change DNS, servers, and the subscription URL all at once.
Proxy, Direct, Config, and Scene in Global Routing control different routing choices; they aren’t subscription format options. Check Update via Proxy separately rather than relying on the Global Routing label. If you need a proxy update but have no working server, ask your provider whether it offers a subscription URL that can be reached directly.
If the connection comes back automatically after disconnecting, check whether Settings → On Demand is triggering it based on a condition. Note the original value before testing, then restore the setting afterward if needed. Automatic connections can make two apparently identical updates use different network routes.
5. Update Completes but the List Is Empty? Check the Content and Import Type
An empty server list doesn’t always indicate a network problem. A server-list subscription and a remote configuration containing rules serve different purposes. If you received a configuration file URL, manage it in Config as a configuration file; the fact that it uses HTTPS doesn’t make it a server subscription for Home.
- Check the group: In Home, expand the subscription you just updated, clear the search field, and distinguish subscription entries from servers you added manually.
- Check the format: Tell your provider you’re using Shadowrocket and confirm that the supplied format is compatible with the app. Don’t try to force an unknown response into another format yourself.
- Check the entries: Ask your provider to confirm that server entries have actually been assigned to your account. Being able to sign in doesn’t mean the subscription will return a non-empty list.
- Check the app: Check the App Store for an available update. Before updating, keep any configuration and existing information you may need to restore; don’t delete the app first.
Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are connection protocol names, not interchangeable subscription format labels. Don’t change a server’s Type to a different protocol just to make it appear in the list; the server-side configuration and client settings must match.
Bottom line: Verify the list and the connection separately
First confirm that valid entries appear in Home, then select a server and test the connection. If the entries are present but access fails, keep the subscription troubleshooting results and check that server’s settings and routing instead of replacing a working subscription URL again.
6. Update Timing and Common Follow-up Questions
Update after your provider announces a URL change, your account is restored, or a change to the server list is confirmed. If an update fails, don’t keep pulling to refresh. Record the result, complete the relevant checks, and avoid hitting rate limits on top of the original problem. Updating a subscription does not restore an App Store purchase or renew a provider plan.
Why do my old servers still work if the subscription won’t update?
Old servers use connection settings already saved in the app; updates contact the subscription endpoint. Keep the old entries and check the endpoint URL and account permissions first. If only direct requests time out, test Update via Proxy using an old server you’ve already confirmed works.
Why does the URL open in a browser but still fail to parse in the app?
The browser may be signed in or may show only a verification page. Ask your provider to confirm that the URL returns compatible subscription entries without requiring interaction in a web page. A URL opening successfully in a browser doesn’t prove that its format is correct.
It updates over cellular but not Wi-Fi. What should I check?
Keep the successful result, then switch back to the original Wi-Fi and check whether it requires web authentication, restricts access, or has a DNS issue. Test one condition at a time. Don’t disable certificate validation to bypass an HTTPS error.
What should I include when contacting my provider?
Include the time and time zone, whether you were on Wi-Fi or cellular, whether you used a proxy update, the exact error text, and whether any old servers still work. In screenshots, hide the full subscription URL, token, password, and server credentials.
Finally, check three things: the relevant group contains entries, a manual update completes, and the selected server can access the intended service. If the first two work but the third doesn’t, see the setup guide for connection and Global Routing checks. Don’t assume the entire subscription is invalid just because one website won’t open.