If you already have a provider and subscription, start by refreshing it manually from Home and checking the result. Then enable Settings → Subscribe → Update on Open if needed. When an update fails, check link authorization, the network request, and content parsing in that order. Don’t delete existing groups before troubleshooting. This guide covers the refresh controls, the limits of automatic updates, and ways to diagnose problems while keeping your existing setup.
What Subscription Updates and Connection Tests Check
Updating a Shadowrocket subscription means requesting the saved subscription URL again and importing the returned server entries into the app. It does not update Shadowrocket itself, and it is not a connection test. Whether a server can connect also depends on its settings, your network, and the status of your service.
The subscription URL is the request endpoint; the server entries shown under Home are the result; and the selected configuration in Config covers settings such as rules. Updating a server subscription does not sync all Config content. Likewise, changing Global Routing does not fetch the subscription again. Identify what each action affects to pinpoint where a problem occurs.
You can check for changes in the list only after the request and parsing are complete. If an update succeeds but the names and count stay the same, the remote content may simply be unchanged. Seeing old entries still there does not, by itself, prove that the request succeeded. Check the app’s update result against the current entries listed by your provider.
Manually Refresh an Existing Subscription from Home
For an initial check, refresh manually from Home. Observe the result of one complete operation, and avoid changing networks, editing rules, and refreshing the subscription all at once. This guide uses the English interface labels; button locations and exact messages may vary with what the app currently displays.
-
Check the Group
Open Home and find your subscription group. Check its name and existing entries first so you don’t mistake an individually added server for a subscription.
-
Check the URL
Open the subscription’s edit screen and check the URL. Don’t change the domain, path, or query parameters. You can return to Home when you’re done; there’s no need to delete the group just to test it.
-
Refresh the Subscription
On Home, pull down from the top of the list and release to refresh. If you have multiple subscriptions, check the result for each group separately. Success for one does not mean they all updated successfully.
-
Check the Result
Wait for the refresh to finish and note the message. Then expand the target group and check its entries and count. If an error appears, keep the existing entries and original message, then troubleshoot using the categories below.
-
Test the Connection Separately
After confirming the update is complete, select one of your working servers and test the connection. If the list updated but the connection fails, check the server settings, service status, or network path.
If you haven’t added a subscription yet, tap “+” in the top-right corner of Home, choose Subscribe under Type, paste in a subscription URL you already have, and save it. Adding a subscription and refreshing an existing one are separate actions. When troubleshooting, don’t keep adding the same URL; doing so can create multiple groups with the same name.
What Update on Open Does—and What It Doesn’t
Go to Settings → Subscribe and find Update on Open. When enabled, the app attempts to refresh subscriptions when opened, reducing the need to refresh manually each time. It does not run background checks on a fixed schedule, nor does it make the local list update immediately whenever remote content changes.
Don’t assume a request started just because the list looks a certain way after returning from the background. The app’s state at the time matters, so check the actual update result. To see whether a URL can be fetched right now, refresh manually from Home; this is easier to observe than repeatedly switching between the foreground and background.
Settings → On Demand controls on-demand connection behavior. It is separate from fetching a subscription list. Enabling On Demand does not replace Update on Open, and enabling Update on Open does not automatically establish a connection. When troubleshooting automatic updates, first confirm that a manual refresh works, then check the setting.
- If manual refresh fails, fix the URL, network, or format issue. Repeatedly toggling automatic updates won’t solve it.
- If manual refresh succeeds, keep that result and check for update feedback the next time you open the app.
- If the list doesn’t change after opening the app, first confirm whether the remote content has actually changed. An unchanged count alone doesn’t mean automatic updates have failed.
- To reproduce the issue reliably, note the network and steps you took. Change only one condition per test.
Expired or Invalid Link: Check the URL and Authorization
Subscription URLs often include parameters used to identify the user. An incomplete copy, an outdated URL, or credentials reset by the server can all cause a fetch to fail. The example below shows URL structure only; it is not a real service address and cannot be used to connect.
https://example.com/sub?token=xxxxCheck the complete URL, not just the domain. In the example, ?token=xxxx shows where a query parameter goes. Real URLs may use different paths and parameter names; don’t modify yours to match this example. In particular, check that copying didn’t add spaces, line breaks, quotation marks, or punctuation from a chat message.
| What to Check | What You May Find | What to Do |
|---|---|---|
| Full URL | The domain is correct, but the path or parameters are missing | Copy the complete URL again from your subscription management page. |
| Access Credentials | The old URL fails, and the server has issued a new one | Verify the new URL, replace it in the existing subscription, and refresh manually. |
| HTTP 401 | The response requires authentication or rejects the current credentials | Confirm that the URL is still authorized. Changing rules won’t fix invalid credentials. |
| HTTP 403 | The server denies access | Ask your provider to confirm your access permissions and any restrictions. |
| HTTP 404 | The resource at the requested path can’t be found | Check whether the path or URL has changed; don’t assume the network is down. |
Use an HTTP status code only if it appears in an actual message or diagnostic. Not every “update failed” error means the URL has expired. Being able to open a website’s homepage in a browser doesn’t prove the subscription URL is valid: the homepage and subscription endpoint are different resources and may have different access requirements.
Timeouts and Connection Failures: Check Each Request Stage
Keep the original network error message whenever possible. The English descriptions below may appear in system network errors; the language and wording depend on the message shown by the app, and the same text won’t appear for every failure. Troubleshooting the stage where the error occurred is more effective than changing several settings at once.
Error: The request timed out.
Why it happens and what to do: The request did not finish within the allotted time. The issue may be with your network or the remote server’s response. First, confirm your current network is working, then try one manual refresh on another available network and compare the results.
Error: A server with the specified hostname could not be found.
Why it happens and what to do: The subscription domain could not be resolved. Check the domain spelling in the URL, then check whether DNS resolution is working on your current network. Don’t replace the hostname with a guessed IP address.
Error: Could not connect to the server.
Why it happens and what to do: A connection to the target server could not be established. Check the port in the URL and the status of the target service. Keep the original URL and ask your provider whether the endpoint is reachable.
For example, an HTTPS URL without an explicit port usually uses 443. If the URL specifies a port, the request uses that port instead. This port belongs to the subscription endpoint and may differ from the connection port used by a server entry. Don’t change every server port to 443 to fix subscription updates.
- Complete any network authentication required on the current Wi-Fi first. If it only lets you open a sign-in page, subscription requests may not complete normally.
- If Wi-Fi fails but cellular data works, the result points to a network-specific issue. Check the Wi-Fi network instead of deleting the subscription right away.
- If the same URL fails on two working networks, check the original error message, URL, and remote service. This alone does not prove there’s a problem with the app.
- If you see a certificate error, check your device’s date and time and the certificate status for the target domain. Disabling security checks is not a general fix.
Proxy, Direct, Config, and Scene under Global Routing affect routing behavior; they are not subscription repair controls. If you need to change routing for a test, note the original setting, change one thing at a time, and restore it afterward. Rewriting the entire Config just because a subscription update failed adds more variables to troubleshoot.
Invalid Format or Empty List: Check the Content After the Request
Receiving a response doesn’t mean it contains a subscription that can be parsed. The endpoint may return a sign-in page, an error message, no content, or data that isn’t compatible with the import method. If the network is working but the list has no usable entries, check the response content type next instead of making more network changes.
| What You See | What to Distinguish | Next Step |
|---|---|---|
| A Web Page Is Returned | The management page URL was copied, or the request was redirected to a sign-in page | Get the subscription URL from your management page; don’t use the page URL instead. |
| The Response Is Empty | The endpoint returned no entries, or no content is available under the current authorization | Ask your provider what entries this URL should return at this time. |
| A Parsing Error Appears | The response format, entry settings, or protocol content isn’t compatible | Confirm the subscription is intended for Shadowrocket, and keep the error message after removing sensitive information. |
| Fewer Entries After an Update | The remote list may have changed; entries aren’t necessarily missing locally | Check your provider’s current list and confirm how many entries you should expect. |
| Entries Updated but Won’t Connect | Fetching a subscription successfully and having a working server are separate things | Check the selected entry’s settings, service status, and connection logs. |
Don’t manually extract, combine, or re-encode a response just because it “looks like encoded text.” Doing so may corrupt the original data and make further troubleshooting harder. If you contact your provider, share when it happened, the network type, the error message, and whether you can reproduce it manually. Share full subscription credentials only through the provider’s designated private channel.
After Recovery: Update First, Then Connect
After fixing the issue, verify the same steps in order: refresh manually from Home, check the group entries, select one of your servers and test the connection, then enable or restore Update on Open if needed. Keeping this order separates subscription endpoint problems from connection problems and prevents an old list from being mistaken for a new result.
- Check the update result: The refresh finished without a new error message, and the target group contains the expected entries.
- Check the selected entry: The remote list may rename or remove entries. Check your current selection again instead of relying on what you selected before.
- Check the rules: Updating a subscription doesn’t replace checking Config. Current settings still affect how connections behave.
- Check automatic updates: Once manual updates work reliably, enable or keep Settings → Subscribe → Update on Open.
- Protect your privacy: Before sharing troubleshooting screenshots, hide access parameters in the URL and any other credentials.
Shadowrocket is a closed-source commercial app for Apple platforms, primarily used on iPhone and iPad. The App Store is the only way to get it. The app purchase and your subscription service are managed separately; buying the app again won’t fix an expired subscription URL. See the App Store page for system requirements and purchase availability.