If you already have a provider and subscription, refresh it manually from Home and check the result, then go to Settings → Subscribe to review the update-on-open option. If an update fails, check the URL, network request, and response format in that order. A successful update means the subscription was retrieved and parsed; it does not guarantee every server can connect or that rules in Config were updated.
What a subscription update changes: the server list, not the app
A Shadowrocket subscription update uses a saved subscription URL to request the server configuration again. If your provider changes server addresses, ports, or authentication details, refreshing the subscription brings those changes to your device. This is separate from updating the app in the App Store, and buying the client does not automatically include a connection service.
Home, Config, and Settings serve different purposes: Home shows servers and connection status, Config manages configuration files, and Settings controls app preferences. Before troubleshooting, identify what you are trying to update so you don't mistake a refreshed server list for a re-downloaded rules file.
A subscription response may also include usage or expiration details, depending on what the provider returns. The presence or absence of usage figures alone does not confirm whether an update succeeded. Check the update result, group entries, and any changes announced by your provider.
Manual refresh: update from Home and check the group
When adding a subscription for the first time, or if you suspect automatic updates haven't run, start with a manual refresh. Note the subscription name, currently selected server, and expected changes announced by your provider. You don't need to delete the existing group to verify an update.
-
Check the subscription
Open Home and find your subscription group. If you haven't added it yet, tap “+” in the upper-right corner, select Subscribe under Type, enter your subscription URL, and save. Don't use a website login URL as a subscription URL.
-
Check the URL
Open the target subscription's edit screen and make sure the URL is complete, especially the query parameters after the question mark. When copying, don't include explanatory text, leading or trailing spaces, or line breaks. Don't change the capitalization of the token.
-
Pull to refresh
Return to Home and pull down on the list to update the subscription. Wait for the request to finish. If you have multiple subscriptions, check the result for the intended group; a successful refresh of another group doesn't mean all subscriptions updated.
-
Check what changed
Review the update result and group entries. If your provider announced a specific new entry, check that it appears. If no changes were announced, an unchanged list does not by itself indicate a failed update.
-
Test the connection
Make sure the currently selected entry is still valid, then test connectivity and try accessing a site. A failed server doesn't mean the subscription URL itself can't be updated; record the results of these checks separately.
Update on Open: Settings → Subscribe
Once manual updates work, go to Settings → Subscribe, find Update on Open, and turn it on. The capitalization or localized wording may vary with the current interface. Look for the option that updates subscriptions when the app opens; this is not the connection trigger condition in On Demand.
This setting reduces the need for manual refreshes; it doesn't mean the app keeps fetching updates at fixed intervals after you close it. When you bring the app to the foreground, an update may still depend on the app's own conditions and the current network. Simply switching back to the app doesn't guarantee that an update has finished.
- Before enabling it: Make sure the same subscription can update manually from Home. Otherwise, an automatic update will run into the same problem.
- After enabling it: Reopen the app when you have a working network, wait for the update result, and check the target subscription. Don't disconnect as soon as Home appears.
- If the network requires authentication: Complete the Wi-Fi sign-in in a browser before trying again. Being connected to Wi-Fi doesn't necessarily mean you have internet access.
- Need the update right away? If your provider has just announced a URL change, refresh manually instead of waiting until you next open the app.
Settings → On Demand controls when a VPN connection starts or stops based on conditions; it isn't a subscription timer. Changing On Demand won't fix an invalid subscription URL or replace the update options in Subscribe.
How updates work: a successful download doesn't guarantee successful parsing
A subscription update involves at least resolving the address, sending a network request, receiving a response, and parsing its contents. If an earlier step fails, the app can't retrieve the full response. If parsing fails, even a server response containing a webpage won't produce usable server entries.
| What to check | What it means | Next step |
|---|---|---|
| HTTP 200 | The server returned a successful response, but the content may still be a login or information page | Confirm that the response contains subscription data compatible with Shadowrocket |
| HTTP 401 / 403 | The request failed an identity or access-permission check | Ask your provider to check the token, expiration, and access restrictions |
| HTTP 404 | The resource at the requested path wasn't found | Copy the current, valid subscription URL again |
| HTTP 429 | The server is limiting request frequency | Stop refreshing repeatedly; wait as directed by the server before trying again |
| The request timed out | The request didn't finish within the allowed time; this doesn't mean the URL has expired | Check your current network and compare with another working network |
Bottom line: check the response before changing local settings
For permission or path-related HTTP statuses, check the subscription URL and service status first. Check the network path first only for issues such as request timeouts or failed domain resolution. Don't change DNS, Global Routing, and the subscription URL all at once, or you won't know which change made a difference.
Subscription update failed: narrow down the cause based on the error
Note the exact error and where it appeared before deciding what to try next. The HTTP statuses below come from the server and may not appear in full in every alert. Follow the corresponding steps only if the actual response includes that status. A generic “update failed” message alone doesn't mean your account has expired.
Error: HTTP 401 / HTTP 403
Cause: The credentials required by the subscription endpoint are invalid, or the server has denied access.
Fix: Check the service status and subscription URL in your provider account. If the token has been reset, edit the existing subscription, replace the URL, and refresh once.
Error: HTTP 404
Cause: The URL path is invalid, the URL was copied incompletely, or your provider has moved the subscription endpoint.
Fix: Copy the complete subscription URL again from your provider and check the path and query parameters. A domain that opens successfully doesn't prove the subscription path is valid.
Error: HTTP 429
Cause: Too many requests were sent in a short period of time.
Fix: Stop pulling to refresh repeatedly. If the server specifies a wait time, try again after that interval. Also check whether repeatedly opening the app triggered extra requests.
Error: The request timed out.
Cause: The network request didn't finish in time. The cause may be the current network, the subscription server, or the connection path used by the request.
Fix: First confirm that regular webpages load, then compare Wi-Fi with cellular once. Change only one condition at a time and note the result.
If the error indicates that content couldn't be parsed, check the subscription type and response body. A login page, balance notice, or web verification page isn't a server list, even if it opens in a browser. Encoded text isn't automatically a compatible format; it must still follow a content structure the app supports.
- Wrong type: Make sure you imported a server subscription, not a Config file URL or account management page.
- Truncated URL: Check whether your messaging app dropped content after a line break, especially in URLs with multiple query parameters.
- Empty response: Ask your provider whether the subscription should return entries. Don't clear the local list as a first attempt to “force a fix.”
- Certificate warning: Check the device's date and time, and report HTTPS certificate issues to your provider. Don't hide the problem by ignoring certificate validation.
Update succeeds, but the list is unchanged or connections still fail
An unchanged list commonly means either that your provider hasn't changed the content or that only entry details—such as addresses, ports, or authentication—were modified. Names and entry counts are visible clues, not proof that the content is complete. Check changes specifically announced by your provider; don't repeatedly delete and re-import just to see “new content.”
If you still can't access sites after updating, troubleshoot the connection separately. The server selected in Home may have been removed or become unavailable. Global Routing modes such as Proxy and Direct, along with Config and Scene, also affect routing behavior. They don't repair a subscription URL. In particular, when using Config, check its current rules and final policy.
- Check the group: Make sure you updated the intended subscription, not another group with the same or a similar name.
- Check the selection: Verify the currently selected server and record the connectivity test and actual webpage access results separately.
- Check routing: Review the current Global Routing mode. If you're using Config, make sure the expected configuration is enabled.
- Check the rules: Review the policies and order for the relevant DOMAIN-SUFFIX, IP-CIDR, GEOIP, and the final FINAL rule. Save the current configuration before making changes; don't rewrite rules just to update a subscription.
Updating a server subscription and updating rules are separate processes. For help understanding configuration fields, see Configuration Field Reference. If you're just getting started, follow the Getting Started guide to check the order for importing, selecting a server, and making your first connection.
Routine checks: keep notes and change one thing at a time
For regular use, you can leave Update on Open enabled and manually refresh after your provider announces a change. If something goes wrong, record enough to distinguish an incorrect URL from a network or parsing failure; there's no need to share the full subscription contents. When contacting your provider, specify whether the issue is with updating or connecting.
- Record the environment: Note whether you're on Wi-Fi or cellular, whether regular webpages load, and whether a connection is currently active.
- Record the result: Note the exact error, HTTP status if shown, when the failure occurred, and whether it happens again on another network.
- Protect sensitive information: Redact tokens, passwords, complete subscription URLs, and identifiable account details.
- Keep your configuration: Until you've confirmed that the new URL returns content correctly, avoid deleting the existing subscription or resetting all settings.
Shadowrocket is a closed-source commercial app available through the App Store, primarily for iPhone and iPad. The one-time app purchase is separate from any connectivity service. Check the App Store listing for pricing and system requirements. Verify Shadowrocket by its developer, Shadow Launch Technology Limited, official icon, and app ID 932747118.