Use this checklist if you already have a subscription URL from your provider but Shadowrocket shows an update error, imports no entries, or stops refreshing an existing list. Keep your current configuration and work through these five checks. The goal is to determine whether the URL is wrong, the server returned no usable content, or the content could not be parsed—not to delete the subscription or change all your network settings right away.
First, distinguish subscription update errors from connection failures
A subscription update retrieves a list of server entries and parses it into records the client can use. If entries are already listed but connections fail, that is an issue at a later stage. An empty list does not prove that every server is unavailable. A successful latency test also does not prove that the subscription URL is reachable; the test target and subscription server may be different addresses.
Before troubleshooting, note the target subscription's name, current entry count, and any message shown on the Home screen. Keep any old entries that still work. Store backups containing credentials only somewhere you control. Don't start by deleting and re-adding the subscription; that removes useful information for comparing what changed.
| What you see | Check first | What you can't conclude yet |
|---|---|---|
| An update error, but old entries remain | The subscription request and its latest response | That all old entries are invalid |
| No entries after the first import | The URL's purpose, response content, and format | That you must change the connection protocol |
| The list is present, but one entry won't connect | That entry's settings and outbound network path | That the subscription definitely failed to update |
| The list count decreases after an update | What the provider returned and any filtering criteria | That the client must have mistakenly deleted entries |
Step 1: Make sure it's a subscription URL, not a webpage
Get the subscription URL from your provider. An account home page, order page, or help page may open in a browser, but that doesn't make it an importable subscription URL. These pages usually return HTML for people to read, not server entries. A URL containing “sub” isn't proof of its purpose either; check the provider's import instructions.
https://example.com/sub?token=xxxxThese example addresses illustrate URL structure only; they won't connect to anything. https:// is the scheme, example.com is the hostname, /sub is the path, and ?token=xxxx is the query string. Real URLs may use completely different paths and parameter names. Don't alter your URL to match this example.
- Go back to where your provider shared the URL and confirm it's meant for a client subscription, not a web login.
- A single server share link is different from a subscription URL containing multiple entries. Don't assume they're interchangeable just because both have a Copy link option.
- To check where you added it, open the add option from Home, go to Add Server, confirm Type is set to Subscribe, and review the URL field.
- Don't import unknown content on the Config screen as a substitute for checking the subscription. Rule configurations and server subscriptions serve different purposes.
Port defaults explain the request destination; they aren't a recommendation to change anything. If the original subscription URL specifies another port, keep it as is. The subscription URL's port is also separate from the connection port of each server in the list.
Step 2: Check that the URL was copied in full
Two URLs that look alike can point to different resources if even one character differs. Common mistakes include copying a Chinese full stop, selecting only the visible part of the URL, missing parameters after the question mark, or pasting line breaks from formatted text. Checking the full string and trying one update is more useful than repeatedly tapping refresh.
- Start: Check for extra quotation marks, explanatory text, or spaces, and make sure the scheme matches the original.
- Middle: Check the hostname, path, and any explicit port. Watch for similar-looking characters and capitalization; paths and credentials may be case-sensitive.
- End: Make sure all query parameters are present and that you haven't included a stray period, comma, or parenthesis from a chat message.
- Encoding: Keep encoded values such as
%2Fand%3Dunchanged. Don't decode them manually or remove&. - Display: An ellipsis shown to save space may not be part of the actual URL. Check the editable field, not just the shortened list preview.
When copying the URL again, use the source page's full-copy option if available. Replace the value in the target subscription's URL field and save. Change only this one variable, run one update, and record the result. Don't also rename groups, change rules, or switch protocols; otherwise, it will be hard to tell what changed the outcome.
Step 3: Check the provider's status and response
If the complete URL still fails, check with your provider: Is your account active? Was the subscription URL reset? Is the service under maintenance? Does the URL have access or rate limits? Buying the client does not include a server plan; purchasing Shadowrocket cannot reactivate an invalid subscription URL.
If the update message or available diagnostic details include an HTTP status code, use the standard meanings below to narrow down the cause. The English text on each card describes an HTTP status; the exact message may differ between updates. If no status code is shown, don't guess which error the server returned.
HTTP 401 Unauthorized
What it means and what to do: The request didn't meet the resource's authentication requirements, possibly because credentials are missing or invalid. Check the full URL parameters and ask your provider whether the address is still valid.
HTTP 403 Forbidden
What it means and what to do: The server denied the request, possibly because of permissions or an access policy. Share the status code and time with your provider so they can check why; don't assume this alone means your plan has expired.
HTTP 404 Not Found
What it means and what to do: The requested path doesn't match a resource. Check whether the URL was truncated or the path changed, then verify the current subscription URL with your provider.
HTTP 429 Too Many Requests
What it means and what to do: The server is rate-limiting requests. Stop refreshing repeatedly and try again after the wait specified by your provider or in the response, such as the Retry-After value.
An HTTP 200 response only means the request succeeded at the HTTP level; it doesn't guarantee that the response body is a valid subscription. A login page, verification page, empty body, or data in an unsupported format may produce no entries. If a browser can display content, that only confirms that particular browser request received a response. The browser's login state, cache, and request conditions may differ from the client's.
Bottom line: Check what the server returned before troubleshooting parsing
If the URL is correct but the list is empty, ask your provider whether it returns non-empty subscription content that Shadowrocket can use. Changing rule configurations won't fix a login page or empty response.
Step 4: Update once, at the right time, and check only the target subscription
Refreshing repeatedly won't fix invalid credentials and may trigger rate limits. If your provider has just reset the URL, changed entries, or restored the service, first confirm the change has taken effect, then run one update and record the result. Don't invent a fixed wait time before retrying; use the provider's instructions or the server's response as your guide.
- Record the starting state: On Home, confirm the target subscription's name and entry count, and check whether its group is collapsed. Make sure search or filters aren't hiding entries.
- Update the target: Use the update action for that subscription. If the current screen offers pull-to-refresh, check which subscriptions it affects so you don't mistake another group's results for this one.
- Wait for the update to finish: Don't trigger repeated requests while one is still in progress. Note the completion message and time.
- Check the result: View the same group again. An unchanged count doesn't mean the update failed; the provider may have returned the same content.
- Know what success means: A successful update only confirms that the subscription was retrieved and parsed. It doesn't mean every entry has been tested for connectivity.
If automatic updates don't run but a manual update works, check the relevant automatic-update options and trigger conditions before investigating background timing. Don't combine a failed manual update with an automatic update that never triggered in the same test. Changing the update interval won't resolve a server access denial.
Step 5: Isolate network issues with a one-variable test
The same subscription URL may behave differently on different networks. A Wi-Fi sign-in page, DNS resolution failure, timeout connecting to the subscription domain, or TLS certificate issue can stop the request before its content is parsed. First make sure the device can access the network, then compare subscription requests. Don't change the server protocol just because the list is empty.
| Test | What to record | Next step |
|---|---|---|
| Keep the same URL and switch from Wi-Fi to cellular | Update fails only on Wi-Fi | Check Wi-Fi sign-in, DNS, and access restrictions |
| Repeat the same request on another network | The same 401 or 403 appears on both networks | Check credentials and the server's access policy first |
| Check the device's date and time | A message refers to the TLS certificate validity period | Correct the device time; if the issue persists, ask your provider to check the certificate |
| Check existing connections and automatic connection conditions | Disconnect, then reconnect immediately | Check On Demand conditions under Settings |
To rule out the current tunnel, first note its original state, then check automatic connection conditions under Settings → On Demand. Temporarily disable the relevant conditions for a test, then restore them. Don't disable TLS certificate verification to hide a certificate error; that changes the security boundary and doesn't prove the subscription content is valid.
Proxy, Direct, Config, and Scene under Global Routing control traffic handling; they aren't subscription repair options. The actual route used by a subscription update may also depend on related settings, so don't assume its outbound path based only on the selected mode. For a comparison test, note the current options and avoid changing DNS, routing, the subscription URL, and server settings at the same time.
Bottom line: Keep one failure you can reproduce
If the same URL fails on only one network, check that network first. If both networks return the same access denial, check the provider's status. If the request succeeds but no entries appear, check the response content. Change one condition at a time.
Still not working after five steps? Prepare a diagnostic report
When contacting your provider, specific details are more useful than simply saying “the update doesn't work.” Don't send the full subscription URL publicly. Start with a redacted report and follow the provider's secure support process to verify your account. This checklist covers both an empty first import and updates that stopped working after the subscription had been working normally.
- Issue: Empty first import, update error, or entries present but unable to connect.
- Time: Date, local time, and time zone. This is when the issue occurred, not the app's update date.
- Steps taken: Updated the target subscription from Home, or imported it using Subscribe under Add Server.
- Evidence: Original message, any visible HTTP status code, and entry counts before and after. Write “not shown” for details that weren't displayed.
- Network comparison: Results on Wi-Fi and cellular, and whether you temporarily changed the connection state.
- Checks completed: URL integrity, whether the address was reset, whether you waited for a rate limit to clear, and whether old entries are still present.
Troubleshoot individual connection issues only after a valid subscription is restored and entries appear normally. To review the import process, read the subscription guide. For a first-time setup, follow the steps in the getting started guide.