This guide is for users who already have a subscription URL from their own provider. First, distinguish node subscriptions in Home from configuration files in Config. Then refresh manually and, once that works, enable updates when the app opens. If an update fails, check the URL, network path, and response format in that order. A successful update means the list was retrieved and parsed; it does not mean every connection in the list works.
1. Identify what you’re updating: node subscriptions vs. rule configurations
In Shadowrocket, updating a subscription means requesting its saved URL again and using the response to update the corresponding node group. If your provider changes server addresses, ports, authentication details, or node names, fetching the subscription again brings your local list up to date. Simply turning the connection switch off and on does not download the subscription again.
This guide uses the Home, Config, and Settings labels found in the iPhone and iPad interface. On other platforms, look for the same setting names; layouts may differ. Before you begin, make sure you’re updating a node list—not a remote rules file on the Config screen.
| Item and location | What gets updated | What it does not mean |
|---|---|---|
| Subscribe group in Home | Node addresses, ports, and protocol parameters returned by your provider. | It does not mean every node has passed a connection test. |
| Remote configuration in Config | Rules and related settings in the configuration file. | It does not refresh every node subscription in Home. |
| Settings → Subscribe | Subscription retrieval behavior, such as updating on app launch or through a proxy. | It does not renew your provider’s plan or restore an expired link. |
This site does not provide, sell, or recommend nodes or subscriptions. The steps below assume you already have an active subscription from your own provider. Check your provider account for service status, remaining data, device limits, and whether the subscription URL has been reset.
2. Refresh manually from Home and check the result
When troubleshooting, start with a manual update so you can observe the error and result. Don’t delete the existing group first: connections in the old list may still work, and deleting it could remove a path you need to restore access. Subscription URLs contain sensitive credentials. When reporting a problem, share only the error text—not the full URL.
-
Check the group
Open Home and find the existing Subscribe group. Check its name and subscription URL. If you haven’t added it yet, tap “+” in the upper-right corner of Home, choose Subscribe for Type, enter your own subscription URL, and save.
-
Pull to refresh
At the top of the Home list, pull down and release to refresh the subscription, then wait for the request to finish. If you have multiple subscriptions, check each group separately. Avoid repeated pulls, which can make the results confusing or trigger your provider’s rate limits.
-
Check the list
Expand the target group and check the node names, count, and any entries your provider has explicitly said were changed. If the remote list hasn’t changed, the count staying the same is normal and doesn’t by itself indicate an update failure.
-
Test the connection
Select an updated node, run Connectivity Test from Home, then try accessing the intended service. If the list updated but the connection fails, check the node settings and network path instead of repeatedly refreshing the same subscription.
Entries managed by a subscription may be recreated or replaced the next time it refreshes. Don’t rely on manual changes to ports or passwords within the group as permanent settings. If you need to keep a separate entry, note its source and purpose, and distinguish it from subscription-managed entries to avoid mistaking old settings for the provider’s latest details.
3. Update on Open: where to find it and when it runs
After a manual refresh succeeds, go to Settings → Subscribe and enable Update on Open. This triggers a subscription update when you open the app; it is not a continuous download task on a fixed schedule, and it does not guarantee updates while the app is in the background. Capitalization and option order may vary by platform, so use the labels shown in your current interface.
- Recommended order: First refresh manually from Home. Once that succeeds, go to Settings → Subscribe → Update on Open and turn it on. This helps avoid mistaking an existing URL problem for an automatic update issue.
- To verify: Leave the app, open it again, and wait for the network request to finish before checking the target group. Switching between screens alone does not guarantee another update.
- Network conditions: An update may fail if the app opens while you’re on a Wi-Fi sign-in page, switching signals, or offline. Restore network access, then refresh manually.
- What it does: Settings → On Demand starts connections based on conditions; it is not a subscription update timer. Enabling On Demand does not replace Update on Open.
To keep the current list while troubleshooting, you can temporarily turn off Update on Open and refresh the target subscription manually. Turn it back on afterward if needed. Automation changes when the request is triggered, not your provider’s access permissions, response format, or plan expiry.
4. How subscription updates work and when to use Update via Proxy
A subscription update first contacts the server hosting the URL, then parses the response. DNS lookup failures, TCP connection errors, TLS handshake failures, HTTP access denials, and invalid response formats occur at different stages. Identify where the request fails to determine whether to change networks, fix the URL, or ask your provider about the response format.
Settings → Subscribe → Update via Proxy makes subscription requests try to connect through a proxy. If the subscription domain is unreachable over your current direct connection but an existing node still works, select that node in Home and connect before enabling this option and refreshing manually. The setting does not create a working route or fix an expired authentication token.
Avoid relying on an unavailable node for updates
If the update depends on a proxy and that node is no longer working, you may get stuck in a loop: you need an update to connect, but need a connection to update. Keep the existing group and try a direct refresh with Update via Proxy turned off, or switch to a trusted network that can reach the subscription domain. Don’t bypass certificate errors by disabling TLS verification.
For example, an HTTPS subscription URL without an explicit port usually connects over TCP 443; the node itself may use a completely different address and port. A successful node latency test does not prove that TCP 443 is reachable on the subscription server. Proxy, Direct, Config, and Scene under Global Routing are connection-routing modes, not four ways to refresh subscriptions. During troubleshooting, change one setting at a time so you can identify the cause.
5. Why updates fail: diagnose the response and symptoms
Note the full error message and when it occurs: only on Wi-Fi, only with Update via Proxy enabled, or with the same status on every network? The messages below are examples of English errors returned by a server or network layer. The app may show a localized description instead; troubleshoot based on its meaning, not an exact wording match.
Error: 401 Unauthorized
Cause: The subscription service did not accept the request’s authentication details. The token may have expired, or the URL may have been reset.
Fix: Sign in to your own provider account, copy a valid subscription URL, replace the URL in the target group, and refresh manually. Don’t guess the token.
Error: 403 Forbidden
Cause: The server denied access, possibly because of account status, source IP, device limits, or access protection rules.
Fix: Check your account and device limits, then give your provider the status code and request time. Don’t assume switching nodes will solve the problem.
Error: 404 Not Found
Cause: The requested path does not exist. Common causes include an incomplete copy, a moved subscription endpoint, or a revoked link.
Fix: Copy the full URL again from your account page and check the path and query parameters. Make sure you haven’t copied only the part before the question mark.
Error: 429 Too Many Requests
Cause: The server has limited the number of requests in a short period. Repeated refreshes may continue to trigger the limit.
Fix: Stop refreshing repeatedly. Wait as directed by your provider or by a Retry-After response header, then try again. Also check whether multiple devices are updating at the same time.
Error: The request timed out.
Cause: The request did not finish within the allowed time. The issue may be with DNS resolution, the connection, the server response, or the current proxy route.
Fix: Compare Wi-Fi and cellular connections, then check Update via Proxy and whether the selected node works. Change one thing at a time.
No status code, but the response cannot be recognized
A completed HTTP request does not guarantee valid subscription content. Even with a 200 response, the server may return a login page, CAPTCHA, expiry notice, or empty body that the app cannot parse as a node list. Ask your provider to confirm that the URL returns a node subscription compatible with Shadowrocket, not an account page or a different type of configuration file.
- Check the URL: Look for leading or trailing spaces, line breaks, and Chinese punctuation accidentally included when copying. In the example URL
https://example.com/sub?token=xxxx, the query parameters are part of the URL. This example cannot be used for an actual update. - Check the content and count: If the group is empty after an update, check your account status and the content returned by your provider first. Don’t immediately delete all local entries.
- Check the date and certificate: If you see a message that a certificate is not yet valid or has expired, check that your device’s date, time, and time zone are correct, then confirm the server certificate status.
- What to include in a report: Share the error message, network type, whether Update via Proxy is enabled, and the steps to reproduce the issue. Hide URL query parameters and authentication details in screenshots.
6. Subscription auto-update FAQ
Auto-update is on. Why hasn’t the node count changed?
An unchanged count doesn’t mean the update failed. Pull down on Home to refresh manually and check for errors, then compare node names or settings your provider has explicitly said were changed. If the remote list is unchanged, it’s expected that the local list stays the same.
Does the app have to stay open for updates?
Update on Open triggers an update when you open the app; the interface does not need to stay in the foreground. To get the latest list right away, return to Home, refresh manually, and wait for it to finish. Don’t infer whether an update succeeded from whether the app was running in the background.
The subscription updated successfully. Why can’t I connect?
Run Connectivity Test on the new list from Home, then check the selected node and Global Routing. Fetching a subscription and using a node are separate requests. Troubleshoot node ports, authentication settings, or access to the destination service separately.
Do I need to reinstall the app after a URL is reset?
Usually, just edit the relevant Subscribe group, replace the URL with your new one, and save. Then return to Home and pull down to refresh. Reinstalling won’t make an old token valid again and may erase local settings that haven’t been backed up.
Can I share my full subscription URL to get help?
Subscription URLs often contain a token that grants access to your account’s node information, so don’t share them publicly. Hide tokens and other sensitive parameters when reporting a problem. If your URL has been exposed, reset it in your provider account and update the saved URL on each device.