At a glance

This guide is for Shadowrocket users who already have a subscription from their own provider. First, distinguish between content that could not be retrieved, content that is not a subscription, and a subscription with no usable entries. Then check the link, provider status, refresh timing, and network path. Keep existing entries during troubleshooting and change one thing at a time. Finally, prepare feedback without exposing credentials and determine whether the issue requires a device-side change or help from your provider.

1. Tell a Request Failure from a Parse Error or Empty List

A subscription is not a fixed set of nodes stored permanently in its link. When you update it, the client first contacts the URL, retrieves the server’s response, and then adds supported server entries to the local list. A failure at any stage can look like an update problem, but each calls for a different fix.

Read the linkRequest the URLReceive contentParse entriesShow the list

In Home, check whether the subscription is simply collapsed, and make sure you are not mistaking the node count in another group for this subscription’s results. Then note the full message shown during refresh. These symptoms can help identify the failing step; do not delete the entire subscription just because the list looks blank.

The interface directions in this guide use Home, Config, and Settings on iPhone and iPad as examples. The same “request, response, parse, display” approach works on Mac, Windows, Android, and Linux. Do not assume that a pull-to-refresh gesture is available on desktop; update from the target subscription’s action menu instead.

2. Check the Full Link: Don’t Use an Account Page as a Subscription URL

Go to your provider’s subscription management page and use its copy-subscription-link option again. Check the beginning of the URL, domain, path, and query parameters locally to make sure the link is complete. The account homepage, order page, and login page in your browser’s address bar are usually not subscription endpoints for the client to fetch.

https://example.com/sub?token=xxxx

The values above are examples for illustrating the structure, not for importing. Fields such as token in a real URL may function as access credentials; do not remove them just because they look like random characters. Do not apply parameter names from another provider to your own link.

  1. Check that there are no extra spaces, line breaks, quotation marks, or non-ASCII punctuation at either end. A line break shown by a messaging app may not be part of the link, so check again after pasting it.
  2. Make sure https:// has not been truncated. Preserve the path’s capitalization, parameters after ?, and & separators exactly as they are.
  3. If the text contains the literal &, copy the link again from the original page. Do not bulk-replace or decode the entire URL without checking it first.
  4. If your provider offers multiple export formats, choose the subscription output explicitly marked for Shadowrocket. Do not treat a web sharing link or a URL to an entire Config file as an equivalent format.

3. Check the Provider’s Response: Handle Status Codes and Empty Content Separately

Being able to open a page in a browser does not mean the URL works as a subscription. A browser session after login may have a Cookie that the subscription request does not, and the server may return a verification page. Even with an HTTP status of 200, the response body may be HTML rather than server data the client can parse.

443
Default port used by HTTPS when none is specified
401 / 403
Check authentication requirements and access policies first
200
A successful HTTP request does not guarantee a valid subscription response

The cards below show standard HTTP response text to explain statuses you may see in error details or provider replies. Shadowrocket may not display these messages verbatim.

HTTP 401 Unauthorized

Cause and fix: The request has no valid credentials, or they have expired. Copy a valid subscription URL from your provider’s page, confirm your account is active, and update the target subscription.

HTTP 403 Forbidden

Cause and fix: The server rejected the request, possibly because of account permissions, source restrictions, or an access policy. Give your provider the time and network type so they can check. Changing client rules will not remove a server-side access restriction.

HTTP 429 Too Many Requests

Cause and fix: The request hit a rate limit. Stop refreshing repeatedly. If the response includes Retry-After, wait as instructed; otherwise, retry after the interval published by your provider.

HTTP 503 Service Unavailable

Cause and fix: The server is temporarily unable to process the request. Check your provider’s maintenance notices and try again later. Repeatedly deleting and adding the local subscription will not fix a server outage.

Takeaway: Check the response body before changing local settings

If your provider confirms that the response is a login page, verification page, or empty content, ask them to fix the subscription output first. Switching protocols or rearranging rules locally cannot turn those responses into server entries.

4. Choose the Right Time to Update: Keep Existing Entries and Test One Change at a Time

After an account plan change, a subscription credential reset, or a provider-side update to entries, the management page and subscription endpoint may not reflect the change at the same time. Repeatedly tapping Update makes the result harder to assess and may trigger rate limits. Follow your provider’s guidance on how long to wait, and record the “last attempt” separately from the “last confirmed successful update.”

  1. Preserve the current state: Note the subscription name, current entry count, and error. If old nodes still work, do not delete the whole group or clear app data.
  2. Confirm the new URL is in use: If you just reset your credentials, make sure you replaced the URL saved in the local subscription. Repeatedly refreshing the old URL will only reproduce the failure.
  3. Update only the target subscription: Find the subscription in Home and update it. If you use pull to refresh, check which subscription requests were actually triggered so results from another subscription do not affect your diagnosis.
  4. Wait for the update to finish before comparing: Check whether the group now has entries, whether the count changed, and whether the error is the same. Finish one test before changing another condition.

Do not treat “import it again” as the default fix. It can create duplicate groups, leave old and new entries side by side, and make it unclear which update worked. If you do need to recreate a record, first make sure the valid link is saved and identify exactly which subscription group you intend to remove.

5. Test Another Network: Separate Subscription Requests from Node Connections

Whether a subscription URL is reachable and whether a node can connect are two separate conditions. A working node does not guarantee access to the subscription domain, and a successful subscription update does not guarantee that every node can connect. Keep the same subscription URL during testing and change only one variable: Wi-Fi or cellular data.

What you seeCheck firstNext step
Fails on Wi-Fi, works on cellularWi-Fi authentication, DNS, and egress policyComplete network sign-in, note the failing network, and leave the subscription unchanged for now
Returns 401 on both networksSubscription credentials and account permissionsCopy a valid URL again and ask your provider to confirm your access
Parse error on both networksResponse body and export formatAsk your provider to check what the endpoint actually returns
Update succeeds, but connections still failServer address, port, and connection parametersContinue with connection troubleshooting; do not keep replacing the subscription URL

If the connection toggle keeps turning itself on during testing, check Settings → On Demand for the conditions that trigger a connection, and note the original settings. Adjust them temporarily only if you understand their effect, then restore them after testing. On Demand controls when a connection starts; it does not control subscription parsing.

Proxy, Direct, Config, and Scene under Global Routing control routing behavior; they are not subscription data formats. Do not try to fix invalid content by rewriting DOMAIN-SUFFIX, GEOIP, IP-CIDR, or FINAL. Base any change to a network path on the actual request result.

6. Still No Nodes? Check the Entries, Then Prepare a Clear Report

If the target group is expanded and the update finishes without a network error but no server entries appear, ask your provider to confirm that the subscription currently contains exportable nodes. An expired account, an inactive plan, server-side filters, or an output problem could all leave the response empty. Your provider must check your account and the response to identify the cause.

Using the same protocol name does not mean every output can be imported as-is. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard each use different connection parameters. Do not replace only the protocol name at the start of an entry or invent a port. Get valid output for Shadowrocket from your provider.

7. Subscription Update FAQ

Why does importing fail when the same link shows content in a browser?

First check whether the content is server data or a webpage. A login form, verification prompt, or account dashboard does not mean the subscription is working. Do not paste an entire webpage’s source into Home. Ask your provider to confirm what subscription output the client can actually retrieve.

Should I delete the old subscription and add it again?

Not yet. Note the target group and error, check whether the original URL is still valid, and try updating it once. Delete the relevant group only if you confirm the record is incorrect or genuinely needs to be recreated, so you do not remove old entries that still work.

I just updated, but there are no new nodes. Should I keep pulling to refresh?

No—do not refresh repeatedly. First check whether the provider’s management page shows the new entries, then wait for the provider’s stated refresh interval. If you get a 429 response, stop retrying. If the list is still empty afterward, send your provider the time, target group, and network test results.

I have nodes, but websites will not open. Is that still a parse error?

That is a different stage. First confirm which server is selected in Home, then check the current Global Routing mode and connection result. If you use Config, also confirm which configuration is active. Once subscription entries are present, repeated imports usually will not fix a server connection or rule-matching problem.

Get Shadowrocket and View the Setup Guide

The iPhone and iPad app is a one-time $2.99 purchase on the App Store. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free: two ways to get Shadowrocket. Check the App Store listing for iPhone and iPad system requirements. Visit the download page for your device or follow the first-time import and connection steps.