Keep your existing subscription, then check the URL, access, response content, account status, and update timing—in that order. Don’t delete all your nodes as a first step. This guide is for Shadowrocket users who already have a service provider and subscription. The steps use Home on iPhone and iPad as an example; the same troubleshooting sequence applies on Mac, Windows, Android, and Linux, though control locations vary by platform.
1. Tell parse errors, empty lists, and connection failures apart
Updating a Shadowrocket subscription involves fetching remote content and then reading node settings from it. A timeout, a login page, an empty response, and unrecognized node settings occur at different stages. “Update failed” alone doesn’t identify the cause or tell you whether your existing nodes still work.
| What you see | Check first | Avoid for now |
|---|---|---|
| Update times out, but old nodes remain | Whether your current network can reach the subscription URL | Deleting an old subscription that still works |
| Parse error after content is received | Whether the response contains subscription data, a webpage, or an error page | Changing the UUID, password, or protocol type at random |
| Subscription group appears, but no nodes are listed | Provider-side node assignment, response content, and list filters | Assuming an empty list means the local configuration is corrupted |
| Nodes appear, but connections fail | Node settings, network, and connection test results | Reimporting the same subscription repeatedly instead of diagnosing the connection |
In Home, first make sure you’re viewing the intended subscription group. Clear any search terms and expand collapsed groups. If node names appear, node data is present; don’t treat this as an empty-list issue. Config rules and node subscriptions in Home serve different purposes. Adding a rule configuration file does not replace importing a node subscription.
2. Check the subscription URL: a complete address matters more than reimporting
Copy the Shadowrocket subscription URL again from your own provider’s account page, then compare it with the saved URL. Don’t copy the account homepage from the browser’s address bar, or use page instructions, button labels, or a login redirect as the subscription URL. The example below shows URL structure only and cannot be used to import a subscription.
https://example.com/sub?token=xxxx- Check the beginning. Make sure the scheme is complete, such as
https://, including the colon and slashes. The URL should not include quotation marks, Chinese parentheses, or explanatory text. - Check the end. Make sure all query parameters after
?are present. An ellipsis in a message preview isn’t part of the URL; copying from a preview card can omit the token. - Keep parameters unchanged.
&separates query parameters, and sequences such as%2Fare encoded. Don’t decode, reorder, or remove characters that look unnecessary. - Check where you copied it from. Use the copy option on the account page whenever possible. If the pasted URL contains a line break, copy it again and check; don’t confuse automatic line wrapping on screen with an actual line break.
- Confirm what the URL is for. A single-node share, a rule configuration URL, and a subscription URL are different inputs. Import it according to the provider’s instructions; don’t judge its purpose by the file extension alone.
If your provider has reset the subscription credentials, the old URL may no longer work even if its format is correct. Update the subscription URL on your device rather than just changing its display name. Avoid resetting the token repeatedly while troubleshooting; other devices using the same URL may be affected too.
3. Use the response to distinguish access issues from content issues
“It opens in a browser” only means the browser received some kind of response; it doesn’t mean Shadowrocket can parse it. A browser may have a logged-in Cookie, while a subscription request can’t rely on the browser’s login state. A login page, CAPTCHA, or maintenance notice is not node data, even if it loads successfully.
The following standard HTTP statuses may appear in a response or diagnostic information. They won’t necessarily appear in a popup with the same wording on every platform. Use a status-specific step only if you actually see that status; don’t infer a particular status code just because the list is empty.
HTTP 401 Unauthorized
Cause and next step: The request is missing valid authentication credentials, possibly because the token has expired. Check the subscription URL again on your account page and ask your provider to confirm the credential status.
HTTP 403 Forbidden
Cause and next step: The server denied access, possibly because of its access policy or your account permissions. Note when it happened and which network you were using, then ask your provider to investigate. Changing a node password won’t fix this.
HTTP 404 Not Found
Cause and next step: The requested path doesn’t exist or the resource isn’t available. Copy the current URL from your account page again and check whether the path was truncated or has changed.
HTTP 429 Too Many Requests
Cause and fix: The request rate has been limited. Stop refreshing repeatedly, wait as instructed by your provider or for the interval specified by the response's Retry-After header, then try updating once.
An HTTP 200 response doesn’t guarantee a successful parse: it may contain an HTML error message or an empty body. If you can inspect the response, check that it contains subscription data in a format provided for the client. Don’t paste a full HTML page into Add Server. Even if you see encoded text, don’t decode it and overwrite the subscription without first confirming the export format.
Bottom line: identify the response before changing the client
If the same URL returns a login page, maintenance page, or empty content, ask your provider about the subscription endpoint. Switching Global Routing or changing Config rules won’t turn a webpage into node data.
4. Check provider-side issues: expiry, quota, and node assignment
Being able to log in to an account and having a working subscription are two different things. The subscription content may be affected by service validity, data quota, account status, or node assignment. Providers handle these situations differently: some return an empty list, some return an explanatory message, and others deny the request. Don’t conclude that an account has expired based on one message alone.
- Validity: Check whether your service benefits are still active, not just whether your account is registered. If you’ve just renewed, confirm that the account page shows the renewal as active.
- Quota: Check whether data is available in the current billing cycle and whether a reset is pending. Ask your provider when the quota will be restored.
- Assignment: Confirm that nodes are assigned to your account and that no export filter is enabled that would exclude them all.
- Export format: If the account page offers client format options, choose the one marked for Shadowrocket. Don’t rename a configuration file intended for another purpose and import it.
- Maintenance: Check the account page for maintenance notices. A temporary endpoint issue doesn’t mean you need to reinstall Shadowrocket.
Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are different protocols, and subscription settings must match the corresponding protocol. If parsing fails, don’t change the protocol type just to make something appear. Ask your provider to confirm that the export is compatible with the client rather than guessing at ports, TLS, or authentication fields.
5. Check update timing and network: change one condition at a time
After a renewal, URL reset, or change to node assignment, the upstream system may need time to sync. There’s no fixed wait time that applies to every provider; follow the account status and provider instructions. Repeated refreshing won’t speed up synchronization and may trigger rate limits, complicating the original issue.
- Record the current state. Note the update time, exact error message, whether nodes are still present, and whether you were on Wi-Fi or mobile data. Don’t clear content that still works.
- Connect to the network. If Wi-Fi requires web authentication, complete it first, then return to Home to update the subscription. The authentication page may cause the subscription request to receive unexpected content.
- Update manually once. In Home, update the target subscription. You can pull down to refresh; check whether the intended group updates rather than looking only at the connection toggle.
- Try another network. If possible, switch from Wi-Fi to mobile data, or the other way around. Keep the subscription URL unchanged so you can tell whether the network is involved.
- Choose your next step based on the result. If it fails only on one network, check that network’s access conditions first. If different networks return the same permission or content error, contact your provider first.
Don’t assume you must connect before updating. Whether a subscription request can reach its destination depends on the network and relevant settings; if the current node is already unavailable, relying on it to access the subscription can create a loop. Config, Proxy, Direct, and Scene under Global Routing are routing modes, not options for fixing a subscription format. If you test routing conditions, change one setting at a time, record its original value, and restore it afterward.
Settings → On Demand controls when connections are made; it doesn’t generate subscription content. Repeatedly toggling On Demand to troubleshoot an empty list adds variables. Keep the current setting and check the URL and response first. Automatic updates can’t fix an expired token either. Once a manual update succeeds, check whether subsequent automatic updates work.
6. Common questions and what to report
Why does parsing fail if the subscription opens in a browser?
First check that the page shows subscription data rather than a login page or notice. The browser’s logged-in state may mask an access issue with the endpoint. Copy the client subscription URL again from your own account page and update it once in Home.
Why is the list still empty after renewing?
First check that the account page shows the benefits as active and nodes as assigned, then wait for synchronization as instructed by your provider. Don’t add multiple copies of the same subscription while waiting, or it may be hard to tell which group was updated.
Another device has nodes, but this one doesn’t. Should I reinstall?
First compare the subscription URLs, update times, and search filters on both devices. The other device may be showing an old cache, which doesn’t prove the current endpoint is working. Update on each device and record the results before investigating device-specific differences.
Should I delete the old subscription before importing again?
Keep the old subscription and any nodes that still work. If you need to test a new URL, use a distinct name and check the update result. Once the new subscription works and you’ve confirmed there are no local changes to keep, you can clean up duplicate entries.
If you still can’t identify the cause, send your provider a record that contains no credentials. Reproducible details are more useful than “it stopped working” and can reduce back-and-forth. Don’t include the full subscription QR code or screenshots that identify your account.
- Device and operating system, and whether the issue occurs on Wi-Fi, mobile data, or both.
- When the issue occurred and your time zone, plus the approximate time of the last successful update.
- The exact error message or HTTP status, and whether you received a webpage or an empty response.
- Whether your account benefits are active, whether the token was changed, and whether the export format was changed.
- What you tried and the result of each step—for example, “the same URL still returns 403 after switching networks.”