At a glance

If you copied a subscription URL from your own provider but importing it adds no nodes, or refreshing an existing list fails, keep the current entry and check the URL, response, and update status first. Then compare results on another working network. The steps below use Home on iPhone / iPad. If nodes already appear but won’t connect when selected, that’s a connection issue—not a subscription parsing failure.

Check the URL type, then update from Home

A subscription URL retrieves a list. Both a provider account page and a subscription URL may start with https://, but an account page usually returns a webpage and can’t be imported as a subscription. Share links starting with ss:// or trojan:// aren’t subscription URLs either: they describe individual nodes and should be imported using the corresponding protocol, not entered in Subscribe.

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

The example above only shows the URL structure; it can’t be used for importing. Query parameters after ? may contain access credentials. Use the subscription URL in your provider account that’s marked for Shadowrocket, and copy the entire address. Don’t omit query parameters, alter encoded characters, or include quotation marks or punctuation from a chat message. The provider determines the path and parameter names; don’t rewrite them to match the example.

  1. Check the original URL

    Copy the subscription URL again from your own provider account. Before importing for the first time, make sure you copied the subscription address—not a login page, dashboard URL, or temporary download link.

  2. Choose the subscription type

    For your first import, open Home, tap “+” in the top-right corner, select Subscribe under Type, paste the full address into URL, and save. If you already have a subscription, don’t add another one yet. First check whether the provider has changed the URL used by the existing entry.

  3. Refresh once

    Return to Home and pull down to refresh. When the request finishes, check the relevant subscription group. If an error appears, note its exact wording. If there’s no error but no nodes are visible, make sure the group is expanded and note the item count before and after refreshing.

  4. Keep the existing entries

    If the existing list still works, keep it. Don’t delete the entire subscription group just to trigger an update. If you need to replace the URL, first confirm that your provider has generated and activated the new address, then update the existing subscription.

Tell request failures, parsing errors, and empty lists apart

Subscription URLNetwork requestServer responseContent parsingList display

A subscription update involves two steps: downloading and parsing. If a request times out, the client may not have received a response at all. If a response arrives but contains a login page, error page, or unsupported format, the content was received but couldn’t be parsed as a list. Another possibility is that the response is readable but the provider generated an empty list—for example, because the account has no exportable entries.

200
A successful HTTP request doesn’t mean the response body can be parsed
403
The server understood the request but denied access
429
The request was made too frequently; wait as instructed

Bottom line: a 200 response still needs a body-type check

If your provider confirms a 200 OK response but Home still shows no entries, ask whether the response contains subscription data Shadowrocket can read, a webpage, or a list with zero entries. Don’t start by changing node ports or adjusting rules.

Opening the URL in a browser doesn’t mean the client receives the same content. The browser may be logged in or may show a webpage after following a redirect. If your provider offers a subscription preview in your account, check whether it contains entries first. To verify the response, ask your provider to check the status code, format, and item count. Don’t paste a URL containing credentials into a public testing site.

Use the exact wording to troubleshoot update errors

First note the message actually shown in the app. The HTTP status text below may come from your provider and may not appear exactly as written in Shadowrocket. If you only see a generic loading message, don’t assume it means the URL expired or the network failed.

Failed to load subscription

Why it happens: This message means the subscription couldn’t be loaded, but it doesn’t tell you whether the download failed or the response was unusable. What to do: Check the full URL, then switch networks and refresh once using the same address. If it still fails, ask your provider to check the response at the time of the request.

401 Unauthorized

Why it happens: The server didn’t receive valid credentials. The subscription parameters may be incomplete, or the credentials may have expired. What to do: Copy the current URL again from your account and ask your provider whether the old link is still valid.

403 Forbidden

Why it happens: The request was denied, possibly because of account permissions, the link’s status, or the server’s access policy. What to do: Ask your provider to confirm the subscription’s access requirements. Don’t repeatedly send the same request.

429 Too Many Requests

Why it happens: The request rate limit was triggered. What to do: Stop refreshing repeatedly. If the response includes Retry-After, wait for the specified time; otherwise, retry once later as advised by your provider.

The list is empty after renewal or a URL change

Payment records, account status, and subscription content generation are separate steps. After renewing, check that the account shows the renewal as active, then confirm that your provider has generated a new list. There’s no universal sync wait time; follow the provider’s stated activation time, if given. Repeated refreshes won’t add entries that the provider hasn’t published yet.

Compare Wi-Fi with cellular data

Change only one condition at a time. Using the same subscription URL and configuration, refresh on your current network and note the result. Then switch to another network that you know has internet access and refresh once. Subscription updates connect to the server that provides the list; node connections use servers in the list. Connecting to an existing node doesn’t prove the subscription server is reachable.

  1. Fails only on Wi-Fi: Check whether the Wi-Fi network requires you to complete a web login. If regular websites load but the subscription request still times out, note when it failed and ask your network administrator or provider to check access to the subscription domain.
  2. Fails only on cellular data: Check whether your system allows Shadowrocket to use cellular data, then test the same subscription again. Don’t change the URL at the same time, or you won’t know which change affected the result.
  3. Same message on both networks: If both return 401 or 403, first check the credentials and account access permissions. If requests work on both but the list is empty, ask your provider to check the exported content instead of changing Global Routing or resetting Config.

Get Shadowrocket and read the user guide

Get the iPhone / iPad version from the App Store for a one-time payment of $2.99. Check the App Store listing for system requirements. The Mac (Apple silicon / Intel), Windows, Android, and Linux versions are free; get their installers from this site’s downloads page.