This guide is for users who already have a subscription URL from their own provider. First, distinguish a failed request from content that cannot be parsed or a successful response with no usable entries. Then check the URL in Subscribe, the provider's response, and update timing. Finally, test the network by changing one variable at a time. Keep your existing configuration during troubleshooting; don't delete entries that still work.
1. Identify where the process fails
Shadowrocket subscription updates request content from a specified URL, then convert supported node records into entries in Home. Saving a subscription URL doesn't mean the server returned valid content. A successful server response doesn't necessarily mean the content includes parseable nodes.
Note exactly what happens: Does an error appear as soon as you add the subscription, or does an update time out? Do existing entries remain while updates fail, or does a newly created subscription group stay empty? Existing entries only show that data was saved locally before; they don't confirm that the latest update succeeded. A working node connection also doesn't prove the subscription URL is still valid.
Key point: Record what happens before changing settings
Note the exact error and time, then try one manual update. If you delete the subscription, switch configurations, and reinstall the app all at once, you won't know which change affected the result.
2. Check the URL saved in Subscribe
A subscription URL should come from your own provider. Don't use an account login, order, or web-sharing page instead. The addresses below are structural examples only and cannot be imported. The path and query parameters may work together to identify your account, so copying just the domain isn't enough.
https://example.com/sub?token=xxxx
-
Copy the original URL
Use the subscription-copy option on your provider's account page and choose the format listed for Shadowrocket. Don't try to read the URL from a screenshot or copy the page title along with it.
-
Check where you add it
In Home, tap “+” in the top-right corner, set Type to Subscribe, and paste the complete address into URL. If the subscription already exists, check that entry first rather than creating duplicate groups.
-
Check the URL boundaries
Check that it starts with
https://and that the ending parameters match the original. Remove any spaces, line breaks, or quotation marks around the URL. Keep the characters inside the parameters unchanged; don't casually remove or edit?,&,=, or percent-encoded characters. -
Save and update
After saving, return to Home and pull down to refresh the subscription list. Wait for the update to finish, then check whether entries appear in the target group. Record the result and avoid sending repeated requests.
A single-node URI and a subscription URL are different types of input. Individual records with formats such as ss://, vmess://, or trojan:// should be imported using the appropriate method; don't enter them as HTTP subscription URLs in Subscribe. Likewise, a subscription page URL isn't a server address for a particular protocol.
A subscription URL may contain an account token. Don't share the full URL in public comments, screenshots, or online decoding tools. If you need help, share the domain and error message, but redact keys in the path and all account-identifying parameters.
3. Check the HTTP status and response content
If the error or your provider's logs include an HTTP status, use it to narrow down the cause. These are standard HTTP response statuses; Shadowrocket may not display these exact messages on every system. If there's no status code, use the actual error text rather than assuming the link has expired.
Error: 401 Unauthorized
Cause: The server's authentication check failed, possibly because the token is expired, missing, or incompatible with the required authentication method.
What to do: Copy the current subscription URL again from your provider account. If the same status persists, ask your provider to check the token's permissions.
Error: 403 Forbidden
Cause: The server rejected the request. This may involve access policies, account permissions, or a security block; this status alone doesn't mean the plan has expired.
What to do: Note the time, network type, and full error text, then ask your provider to check the request. Don't keep refreshing to try to bypass a restriction.
Error: 404 Not Found
Cause: The requested path doesn't exist. The URL may have been cut off, an old address may have been disabled, or the server may be intentionally hiding the resource.
What to do: Compare the path and parameters with the current URL on your account page. Don't guess the endpoint path. If a new URL still fails, ask your provider to investigate.
200 OK means the request succeeded at the HTTP level. The response body may still be a login page, security verification page, maintenance notice, or empty content. Even if it opens in a browser, that doesn't mean the client should generate nodes from it. Your browser may also send account cookies; a subscription request isn't the same as an authenticated web session.
- If the response body starts with
<!DOCTYPE html>or<html>, first check whether you received a web page instead of subscription data. - If your provider offers multiple output formats, use the one intended for Shadowrocket. Changing the file extension alone won't convert the content.
- Some subscriptions wrap text in Base64 encoding. Encoding isn't encryption, and it doesn't guarantee that the records inside are valid. Don't submit the raw content to a third-party website.
- If the response is empty or contains only explanatory text with no node records, first check your account's available entries and the server output—not Global Routing.
4. Check provider status and update timing
An empty subscription group may mean the server currently has no available entries for your account, or that the subscription output hasn't synced with your account status. Account balance, plan status, device limits, and subscription permissions are separate fields. Check your provider's own documentation; an empty list in Shadowrocket alone can't confirm any of them.
- Check your account: Sign in to your provider's site and check the service status, expiration date, and whether the page lists any available entries. If the account page is empty too, contact your provider first.
- Check for URL changes: If you recently reset your subscription token, the old URL may no longer work. Compare the saved address in Home with the new URL; matching domains alone aren't enough.
- Allow time for server-side updates: After changing a plan or restoring service, wait for the processing time specified by your provider before updating. Don't assume every interface syncs as soon as you submit a change.
- Check request limits: If you get
429 Too Many Requests, stop updating repeatedly. If the response includesRetry-After, wait as directed; otherwise, ask your provider how often you can update.
Don't refresh every few seconds as a troubleshooting method. Repeated requests may trigger rate limits and add an access issue to the original format problem. If your existing entries still work, keep them for now and tidy up duplicates only after confirming the new subscription content is valid.
Key point: If the account page is empty too, address the server-side issue first
If the account page has no available entries, or your provider confirms that the subscription interface hasn't generated data yet, switching protocols, rules, or DNS won't create nodes. Ask your provider to confirm that the interface returns valid records, then update in Home.
5. Test the network and connection one variable at a time
Request timeouts, DNS lookup failures, and TLS errors occur at different stages. A timeout may mean the connection wasn't established, or that the response never finished. For certificate errors, check the system time, target domain, and server certificate; don't bypass certificate checks. Change only one condition at a time so you can compare results.
-
Record the current state
Note whether you're using Wi-Fi or cellular data, the Home connection toggle status, the current Global Routing option, and the exact error. Don't change DNS and rules at the same time.
-
Switch networks
Keep the subscription URL and connection state the same, then update once over Wi-Fi and once over cellular data. If it fails on only one network, check that network's sign-in requirements, DNS, or access restrictions first.
-
Check automatic connections
If the connection comes back on after you turn it off manually, go to Settings → On Demand and check for enabled triggers. Note the original settings, temporarily disable automatic connections for the test, then restore them.
-
Compare before and after connecting
Only if you already have a working node, compare update results while disconnected and connected. You can't connect using a subscription that hasn't imported successfully, and you shouldn't assume subscription requests always go through the selected node.
Config, Proxy, Direct, and Scene under Global Routing control how traffic is handled; they don't turn a web page into node entries. DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL in Config are rule keywords, not switches for fixing subscription parsing. For an empty list, check the response content first, then decide whether rules or the outbound route need attention.
Being able to open your provider's homepage only proves that the page is accessible on your current network. It doesn't prove that the subscription endpoint, redirect target, or account-identifying parameters work. For a meaningful comparison, record results for the same subscription request.
6. When to contact your provider and what to include
Contact your provider if the latest URL keeps returning an authentication error, the account page shows entries but the interface returns none, or the provider's recommended format still can't be parsed. Ask them to check interface permissions, response content, format compatibility, and request logs. This is more useful than repeatedly deleting local entries.
- Time: Give the date, exact time, and time zone so the provider can check its server logs.
- What you did: Say whether this was the first update after adding Subscribe in Home, or an existing subscription that failed during a manual refresh.
- What happened: Quote the error exactly. Note whether the original entries are still there, whether the target group is expanded, and whether the list stays empty.
- Environment: Include your system type, network type, connection status, and results from tests where you changed one variable at a time. Don't share account details from other apps.
- Protect your information: In public reports, share only a redacted domain and a screenshot of the error. Send a token only through a private support channel confirmed by your provider.
Once the issue is resolved, return to Home and update manually once. Confirm that entries appear in the target group, then test a listed entry. A populated list and a successful connection are separate checks: the first confirms the subscription was fetched and parsed; the second also depends on the node address, port, protocol settings, and current network. If entries appear but won't connect, troubleshoot the connection rather than rebuilding the subscription.
This guide assumes you already have a provider and subscription of your own. This site doesn't provide, sell, or recommend nodes or subscriptions. The client purchase and network service are separate; buying the client doesn't include a service plan.