Shadowrocket Subscription Update Guide: Manual Refresh, Update on Open, and Troubleshooting

Learn how to refresh a Shadowrocket subscription manually or on app launch, plus how to troubleshoot expired links, network issues, and unsupported formats.

At a glance

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 locationWhat gets updatedWhat it does not mean
Subscribe group in HomeNode addresses, ports, and protocol parameters returned by your provider.It does not mean every node has passed a connection test.
Remote configuration in ConfigRules and related settings in the configuration file.It does not refresh every node subscription in Home.
Settings → SubscribeSubscription 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

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

Trigger updateResolve domainEstablish connectionReceive responseParse listUpdate group

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.

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.

Download Shadowrocket for free