· Troubleshooting · About 7 min

Shadowrocket Subscription Not Parsing or Empty Server List: Check the URL, Provider Status, and Refresh Timing

If a subscription fails to parse or shows no servers, check the URL, your provider’s status, and when you refreshed. Find each check in Shadowrocket.

At a glance

If you have your own provider and subscription URL but don’t see server entries in Shadowrocket’s Home, first check the add type and the entire URL. Then confirm that your provider is returning a server list, and refresh once manually to compare the results. The steps below use the iPhone / iPad interface. If entries are already listed but won’t connect when selected, troubleshoot the connection instead of repeatedly re-importing the subscription.

First, tell download failures, parse failures, and empty lists apart

A subscription appearing in Home only means it has been added to the app; it doesn’t mean the server list updated successfully. An update first sends a request to the subscription URL, then reads the response and identifies its server entries, and finally displays the results in Home. If the download fails, the app may not have received a readable response. If parsing fails, check whether the content is in the expected format. If the list is empty, confirm that your provider has actually assigned entries to your account. A generic error message may not reveal which step failed.

Subscription URLNetwork requestServer responseContent parsingList display

Failed to load subscription

Possible cause: The URL may have expired, or the request may not have retrieved readable subscription data. What to do: Check your provider’s account portal to confirm that the URL is active and a server list has been generated. Then pull down to refresh in Home once and note the result.

401 Unauthorized

Possible cause: If your provider confirms that the subscription request returned this HTTP status, the request usually lacked valid authentication—for example, the token in the URL may have expired. What to do: Copy the complete URL again from your account portal. If the new URL still returns this status, ask your provider to check its authentication requirements. This is not a fixed message displayed by Shadowrocket.

Check the URL format: Add it from Home using Subscribe

First, make sure you copied the subscription URL specifically provided by your service provider—not a URL for the account portal, sign-in page, or help page, and not a share link for a single server. A URL that opens in a browser won’t necessarily work as a subscription. The example below shows only the URL structure; it can’t be used to import servers:

https://example.com/sub?token=xxxx
  1. Copy the current URL

    Copy the current subscription URL from your provider’s account portal. Don’t copy a shortened preview with an ellipsis from a chat message, and don’t include trailing punctuation, quotation marks, or a line break.

  2. Choose the add type

    In Shadowrocket, open Home, tap + in the top-right corner, then choose Subscribe under Type. This adds a URL for retrieving a server list; it doesn’t import a rules file into Config.

  3. Check the complete URL

    Paste the URL and check its scheme, hostname, and path, as well as whether all query parameters after ? are intact. Preserve any & characters and percent-encoding exactly as they appear in the original URL. Don’t remove parameters or manually convert encoded characters based on guesswork.

  4. Save, then refresh

    Save and return to Home, then pull down in the server list to refresh. Wait for the result before checking whether the subscription has new entries. If you’ve already added this subscription, check the existing entry instead of adding duplicates to test it.

Subscription parameters may contain account credentials. Check the complete URL only on your own device and in your provider’s account portal. Don’t paste a real URL into a public parsing tool, post, or screenshot. When describing its format, replace the token and any other account-identifying information with fake values.

Check the provider’s response: HTTP success doesn’t guarantee a valid list

If the URL is correct but still fails to parse, check your provider’s account portal to see whether the subscription is enabled, whether servers have been assigned to your account, and whether the subscription URL has changed. Being able to sign in to the portal only confirms that your browser can access the account page. The browser may have an active login session; Shadowrocket won’t automatically use that session when requesting the subscription URL.

200
HTTP OK: The request succeeded, but the response body may not be a valid list
401
HTTP Unauthorized: The request lacks valid authentication credentials
429
HTTP Too Many Requests: Too many requests in a short time

Bottom line: Once the URL is correct, ask your provider what it returned

If refreshing in Home still fails with the complete URL, give your provider the refresh time and time zone and ask them to check the HTTP status, whether the response was a list or a web page, and whether the list contained entries. Confirm these details before deciding whether to change the URL or output format.

Check when you refreshed: Change one thing at a time

After enabling a subscription, resetting a token, or changing account assignments, first confirm that the change has taken effect at the subscription URL, then refresh in Home. Renewals or assignment updates may continue to use the same URL. If your provider explicitly reset the URL, update the saved address instead of refreshing the old one. There’s no universal wait time; follow the status provided by your service provider.

  1. Note what you see before refreshing. In Home, confirm which subscription you’re checking and note the visible number of entries and the exact error message. Existing entries remaining visible doesn’t prove that the latest refresh succeeded.
  2. Refresh once after confirming the change. Pull down in Home and check whether entries appear, whether existing entries changed as expected, and whether the same message is still shown. If your provider confirms a 429 response, wait as they advise before retrying; don’t refresh repeatedly.
  3. Compare networks only if you suspect a network issue. If the refresh times out on your current network, try the same URL on another available network using the same device. Don’t change the URL and account settings at the same time. If it fails on only one network, first check whether the subscription URL is reachable on that network; this alone doesn’t mean the list format is wrong.
  4. Stop re-importing once entries return. If the expected entries appear in Home but one won’t connect, use Connectivity Test to check the connection. This test doesn’t verify the subscription response format and can’t replace checking the list after refreshing.

Still empty? Prepare the details your provider needs

When reporting the issue, describe “subscription updates” and “server connectivity” separately. Say whether the list has been empty since you first added the subscription or whether an existing list became empty after a change; these cases require different server-side checks. Keep the existing entries and error details for reference. You don’t need to reinstall the app or clear Config to test the same subscription response.

Download Shadowrocket