This guide is for users who already have a provider and subscription. First, refresh manually from Home and check the result, then enable automatic updates when the app opens. If an update fails, check the link, network, HTTP response, and content format in that order. Get your subscription from your provider. A successful update only means the subscription content was read; it does not guarantee that every connection in it works.
Subscription Updates vs. Connections
In Shadowrocket, a subscription retrieves server configurations from an address. Updating a subscription requests that address again and refreshes the associated group with the returned content. This is not an app update or a Config file update. A server configuration added individually has no subscription source, so pulling down to refresh will not retrieve a new address, port, or credentials from your provider.
Each step can fail differently: an incorrect address may be unreachable; a network issue may cause the request to time out; and a server may respond successfully with a login page that cannot be parsed as subscription data. So, seeing old entries still listed in Home does not mean the latest update succeeded. Check the refresh status, the subscription group contents, and any changes announced by your provider.
Manually Refresh from Home
Start with a manual refresh so you can check the result, then enable automatic updates. This helps distinguish a trigger that did not run from a failed subscription request. If you already have a subscription group, start at step 2; there is no need to add the same address again.
-
Check for a Subscription
In Home, check whether the subscription group is already listed. To add one for the first time, go to Home → “+” in the top-right corner → Type → Subscribe. Enter the full subscription URL provided by your service provider, save it, and return to Home.
-
Pull to Refresh
Pull down from the top of the list in Home to refresh. Keep the app in the foreground and wait for the refresh to finish. Avoid repeated pulls or switching networks while a request is in progress.
-
Check the Result
Check the notification after the refresh finishes, then review the relevant group. If your provider announced additions, removals, or renamed entries, look for those changes. If nothing changed on the remote end, the list may look the same even when the update succeeds.
-
Test the Connection Separately
After confirming the update succeeded, select the server you want to use and test access. Record whether the subscription updated and whether the server connected; this helps avoid mistaking a connection failure for an invalid subscription.
If you have multiple subscriptions, check which group the update status refers to. A successful update for one group does not mean the others were updated. Updates may change entries managed by your provider, so avoid making long-term personal edits to entries generated by a subscription. Save any information you need before editing.
Set Up Update On Open
Go to Settings → Subscribe → Update On Open. When enabled, the app attempts to update subscriptions as configured when it opens. This setting controls subscription retrieval, not automatic system VPN connections. Settings → On Demand controls on-demand connections; it is a separate setting.
- First, manually refresh from Home and confirm that the current address can be read successfully.
- Go to Settings → Subscribe and turn on Update On Open.
- Close the app, then open it again and check the refresh status and result in Home. Do not rely only on whether the number of entries changed to determine if an update was attempted.
- If manual updates work but Update On Open does not produce the expected result, check that the setting is still enabled and note which network you used and how you reopened the app.
“On open” does not mean the app keeps polling in the background or updates at fixed intervals while the device is locked. The system manages background activity separately. To check a subscription immediately, manually refresh from Home so you can verify the result. If automatic updates encounter a network or authorization error, troubleshoot it as described below; enabling the setting cannot fix an invalid address.
Check the URL and Authorization
Subscription URLs often contain credentials. Copy the full URL, including all query parameters, and do not truncate anything after the question mark. Make sure you are using the subscription endpoint, not the provider’s webpage. The example below uses dummy values and is not a working subscription; do not import it to test.
https://example.com/sub?token=xxxx- Check the full URL: Make sure there are no extra spaces, line breaks, or punctuation added by a messaging app. Do not remove parameters just because they look complicated.
- Check the source: Use a subscription URL from your provider that is intended for Shadowrocket—not an account homepage, payment page, or announcement page.
- Check the validity: Ask your provider whether your subscription access is active, the URL has been reset, or request frequency is limited.
- Check whether the URL changed: If your provider resets the token, update the subscription URL saved in the app. Reopening the app will not replace an old token with a new one.
If an error includes an HTTP status code, use the cases below to narrow down the issue. A status code describes how the request was handled; it does not confirm that the subscription format is valid. Even with a 200 response, check whether the app parsed the content successfully.
Troubleshoot Network Errors and Failed Requests
The following are examples of English error messages that a network request may return. The exact wording depends on the current interface and system response. Keep the actual error when troubleshooting instead of grouping every failure under “update failed.” Change one condition at a time, then try a manual refresh again to see what made a difference.
Error: The request timed out.
Cause: The request did not finish in time. This may be related to your network or the subscription server’s response.
Try this: First, check that regular webpages load. Then try switching between Wi-Fi and cellular. If both time out, ask your provider to check the subscription endpoint.
Error: A server with the specified hostname could not be found.
Cause: The subscription hostname could not be resolved. The domain may be mistyped, DNS may be having issues, or the server’s domain may have changed.
Try this: Check the domain in the original URL, then retry on another available network. If it still fails, ask your provider to confirm the current URL.
Error: Could not connect to the server.
Cause: A connection to the server could not be established. The server may be down, the port may be unreachable, or network access may be restricted.
Try this: Keep the URL unchanged and compare results across different networks. If only this subscription fails, send your provider the error details with sensitive information removed.
If the device’s date and time are significantly wrong, HTTPS requests may also fail with certificate errors. Check the date and time in your device’s system settings first. Do not bypass certificate validation to fix a subscription error. HTTPS URLs usually use port 443; do not add or change the port unless your provider specifies a different one.
- If the device has no network connection, restore it first, then retry the subscription request.
- If an update fails while connected but succeeds after disconnecting, note the difference and check your current routing and connection status. There is no need to delete the subscription right away.
- Proxy, Direct, Config, and Scene under Global Routing are routing modes, not subscription format options. Switching modes will not fix an expired token or incompatible content.
- If you get HTTP 429, stop refreshing repeatedly. Wait as directed by your provider before trying again to avoid triggering further rate limits.
Unsupported Format, Empty Lists, and Old Entries
A request can complete successfully and still fail to import. Common causes include the endpoint returning an HTML login page, verification page, error message, or empty content instead of subscription data the app can recognize. Do not assume a URL is a valid subscription just because it opens in a browser; the browser may be signed in, while the app’s request may not have the same access.
| What you see | Check first | Next step |
|---|---|---|
| Request returns a response, but it cannot be parsed | Check whether the response is a login or error page | Confirm that you are using a subscription endpoint intended for Shadowrocket |
| No usable entries after refreshing | Check whether the remote service returned an empty list or an authorization prompt | Ask your provider to confirm your subscription content and account status |
| Old name still appears after your provider renamed it | Check whether this update succeeded and whether you are viewing the right group | Check the target subscription URL and refresh result before comparing entries |
| The list updated, but connections fail | Check the server address, port, credentials, and current network | Troubleshoot the connection instead of refreshing the subscription again |
Type → Subscribe retrieves a set of configurations from a subscription URL. It is not where you choose Shadowsocks, VMess, VLESS, Trojan, Hysteria2, or WireGuard. The subscription content determines the protocols and connection fields. If your provider offers multiple format options, ask which one is intended for Shadowrocket; do not guess the format by changing the URL suffix.
Do not clear all entries just to rule out a format issue. Save the error details and confirm that you have the complete, valid subscription URL before considering replacing the subscription. If you delete the old group and the new URL still does not work, you will lose the original information and make it harder to compare results.
Verify the Result and Gather Details
After troubleshooting, return to Home and try a manual refresh again. Classify the result as one of three cases: the request failed, the request completed but parsing failed, or parsing succeeded but the connection failed. Once you know which step is affected, decide whether to check the network, ask your provider to verify the subscription, or continue troubleshooting the connection.
- Record the steps: For example, pull to refresh in Home, or enable Settings → Subscribe → Update On Open and reopen the app.
- Record the exact error: Keep the HTTP status code or system network error. Before taking a screenshot, hide the full subscription URL, token, password, and personal account details.
- Record network conditions: Note whether the issue occurred on Wi-Fi or cellular, whether a connection was active, and whether the result changed after switching networks.
- Record list changes: Note whether all subscriptions failed or only one group, and whether the changes announced by your provider appeared.
Do not post subscription URLs containing tokens in public comments or public testing pages. When reporting an issue, share only the domain and error details with sensitive information removed. If full credentials are required, use the private support channel specified by your provider. Once manual updates work reliably, you can leave Update On Open enabled for everyday use; check the refresh result if something goes wrong.