Subscription issues in Shadowrocket should be checked in four stages: the URL, the request, the response, and how the list is displayed. Assuming you already have a subscription from your own provider, this guide explains how to verify the URL, distinguish a timeout from a parsing error, check update options in Settings → Subscribe, and confirm recovery without changing your existing configuration.
First, tell a parsing error from an empty list
A subscription update first fetches data, then parses it into server entries. An incomplete request, a login page returned by the server, or an unrecognized response can all prevent new entries from appearing. An empty list can also result from search filters, a collapsed subscription group, or an empty response from the provider. The list alone does not reveal which step failed.
Go back to Home, clear any active search, expand the relevant subscription group, and check whether all entries are missing or only one group is empty. Note the full message and time of the update attempt. If the previous entries are still there, leave them in place for now; an unsuccessful update does not mean the existing configuration has stopped working.
- If it fails after waiting: Check whether your current network can reach the subscription URL and whether the update needs to go through an existing proxy connection.
- If parsing fails almost immediately: Check whether the response is subscription data rather than an account page, error notice, or access verification page.
- If the update returns zero entries: Check the display filters first, then ask your provider whether the subscription currently contains any available entries.
- If entries appear but connections fail: This is a separate connection issue. Check the server parameters and run Connectivity Test rather than repeatedly importing the subscription.
Check the subscription URL: full address and authentication parameters
Copy the Shadowrocket subscription URL again from your provider's account page, then compare it with the address saved in the app. An account homepage, plan details page, or individual server share is not a subscription URL. Make sure you copy the entire address, especially the authentication parameters after the question mark.
https://example.com/sub?token=xxxxThe address above is an example and cannot be used to import a subscription. Here, https:// is the scheme, example.com is the domain, /sub is the path, and ?token=xxxx represents a query parameter. Your provider determines the actual path and parameter names; do not modify your URL to match this example. A token in a subscription URL is usually tied to access, so protect it like an account credential.
- Check that there are no extra quotation marks, spaces, line breaks, or punctuation added by a messaging app at either end of the address. Do not remove valid encoded characters that are part of the URL.
- Make sure separators such as
?,&, and=are intact. If you copied text from webpage source, check that a parameter separator was not saved as the literal&. - Preserve the original token's letter case and encoding. Do not decode
%2F, replace plus signs, or reorder signed parameters. - If your provider recently reset the subscription URL, copy the new one. The old address may have been revoked even if it looks similar.
Opening the URL in a browser can help with troubleshooting, but it is not conclusive. A browser may use cookies from a signed-in account, while the app's subscription request may not share that login session. Conversely, seeing a long string of encoded text or being prompted to save content does not mean the response is invalid. Check whether the URL can independently return subscription data supported by the app.
Inspect the response: timeouts, authentication failures, and unexpected content
Being able to reach a domain does not mean its subscription endpoint is working, and receiving a response does not mean it contains a valid subscription. If the app, diagnostic log, or provider gives you an HTTP status code, record it along with the time. The standard HTTP statuses and network error terms below may not appear verbatim in Shadowrocket every time.
HTTP 401 Unauthorized
Cause: The server did not accept the credentials in the request. The token may have expired or authentication information may be missing.
What to do: Copy the subscription URL again from your account page and ask your provider to check its authentication status.
HTTP 403 Forbidden
Cause: The server rejected the request. This could involve account permissions, source restrictions, or access policies; the status code alone does not prove that your plan has expired.
What to do: Check your account status, then give your provider the request time and status code and ask whether access is restricted.
HTTP 429 Too Many Requests
Cause: The server is limiting request frequency. Repeated refreshes can make troubleshooting take longer.
What to do: Stop retrying. Wait as directed by the server or your provider, then try one update.
Request timed out
Cause: The request did not finish within the timeout period. The issue may be with the network path or the subscription server.
What to do: Compare Wi-Fi and cellular data, then check whether Update via Proxy requires an already working proxy connection.
A response that is an account login, maintenance notice, or access verification page cannot be parsed as a server list, even if its HTTP status is 200. Ask your provider to confirm that the URL returns a subscription format supported by Shadowrocket, not a webpage that requires interaction. Do not copy text from an error page into server fields as if it were server configuration.
Bottom line: check what the server returned before changing parsing settings
Repeatedly importing the same URL will not help if the response is not subscription data. Ask your provider to confirm the response content and access authorization, then update once more.
Check Settings → Subscribe and the update route
In Settings → Subscribe, review the options related to subscription updates, especially Update via Proxy. This changes the route used for the update request; it cannot fix an incorrect URL or turn an unsupported response into a valid subscription. Change one setting at a time and note the result.
- Try one update with the current settings first: Update the subscription from Home, for example by pulling to refresh. Watch for an error message and avoid triggering repeated requests.
- Consider a proxy route if direct access times out: If you already have a working server, select it and connect. Then go to Settings → Subscribe, check and enable Update via Proxy, and update again.
- Check that the proxy actually works: Use Connectivity Test on Home to help assess the connection. A test result only shows connectivity under those test conditions; it does not guarantee access to the subscription endpoint.
- Compare with the direct route if the proxy route fails: If your current network allows direct access to the subscription endpoint, turn off Update via Proxy and try once more. Do not change DNS, Global Routing, and the subscription URL at the same time.
If the list is empty and no existing server is available, turning on Update via Proxy alone cannot create a working connection. Check direct access first or ask your provider about the access requirements for its subscription endpoint. Fetching a subscription and connecting to a server are separate steps. A setting cannot bypass the first step when the configuration needed for the second is not yet available.
Choose when to update and avoid mistaking old results for a new failure
After your provider restores account access, resets a token, or changes subscription contents, confirm the change has taken effect before updating manually. Do not assume all subscriptions use the same refresh interval, or that leaving the app in the foreground means an update has completed. Check the actual automatic update settings in Settings → Subscribe.
| Situation | First step | Then check |
|---|---|---|
| Account access just restored | Confirm the permissions are active on your provider's account page | After updating manually, did the expected entries appear? |
| Subscription URL just reset | Replace the saved address in the app with the new one | Is the app still requesting the URL tied to the old token? |
| Just switched from Wi-Fi to cellular data | Wait for the current network connection to stabilize | Does the same URL still time out on the new network? |
| Received HTTP 429 | Stop refreshing repeatedly and wait as instructed | Is the next request still being limited? |
| Provider confirmed subscription content was changed | Update manually once | Did the entries and parameters in the relevant group change as expected? |
If an update fails, the old entries may still be visible, so seeing servers in the list does not mean the latest update succeeded. Likewise, unchanged entry names do not prove that nothing was updated; the server may have changed only the connection parameters. Check the update message, the actual entries, and the changes confirmed by your provider—not just the names.
- After recovery, clear the search, expand the relevant subscription group, and check for the expected servers.
- Select a server from that subscription, run Connectivity Test, then test the service you actually need to access.
- If the entries are back but connections still fail, check the server address, port, and protocol parameters instead of troubleshooting the URL again.
Frequently asked questions and what to include when reporting an issue
Why does the URL open in a browser but fail to parse in the app?
Check exactly what the browser displays. A login page or account dashboard does not prove that you received subscription data. Even if you see subscription text, confirm with your provider that its format is supported by Shadowrocket. Do not paste the entire browser page into a server field.
What should I do if enabling Update via Proxy stops updates from working?
First confirm that the selected existing server can connect, then run Connectivity Test on Home. If the proxy route is unavailable but the subscription endpoint can be reached directly, go to Settings → Subscribe, turn off Update via Proxy, and update once. Record how the two results differ.
The list is empty. Should I delete the app and import the subscription again?
First clear the search on Home and expand the group, then check the subscription URL and your provider account status. Reinstalling adds work to restore your existing settings and cannot change what the server returns. Keeping the old configuration makes it easier to compare before and after the failure.
Why does Connectivity Test still time out after a successful subscription update?
Successfully fetching a subscription means the configuration was retrieved and parsed; it does not mean every server is reachable. Make sure the expected server is selected on Home, then ask your provider to verify the address, port, and required protocol parameters. Do not change the subscription token just because a connection test failed.
If your provider needs to investigate, share enough information to identify the issue while protecting your subscription credentials. Do not post a complete subscription URL, QR code, or screenshot containing a token in a public discussion. Share the full URL only if necessary, through the private support channel specified by your provider.
- What happened: Was the request timed out, did parsing fail, or did the update leave no visible entries?
- Time and network: Note when it happened and whether you were on Wi-Fi or cellular data. Do not disclose your personal network address.
- Update method: State whether Update via Proxy was enabled and whether a working connection was established at the time.
- Response details: Include the full error message or the HTTP status code you observed, and say whether a login page was returned.
- What you tried: Describe the results before and after switching networks or changing one setting. Avoid vague reports such as “it never works.”
Once you have completed these checks, the next step should be clear: correct an incorrect URL, ask your provider to resolve an access issue, check the update route for network timeouts, or verify the response format. Do not change several settings at once before identifying the cause; otherwise, it will be hard to tell what made the difference.