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

What a Subscription Refresh Actually Updates

When Shadowrocket updates a subscription, the client requests content from the subscription URL and adds any recognized node details to the corresponding subscription group. This does not update the app or renew a service plan. This guide assumes you already have your own provider and subscription; get subscription links and nodes from your provider. This site does not provide, sell, or recommend nodes or subscriptions.

An update may change node names, server addresses, ports, or authentication settings. It may also remove items that your provider has deleted from the subscription. For this reason, manual edits to subscription entries may not last: a later update can overwrite them with remote content. If you need to preserve special settings, note their original values and check whether the item is still managed by the subscription.

The subscription URL's port is different from the port used to connect to a node. For example, an HTTPS subscription request may use the default port 443, while a returned node uses a different port. Successfully downloading a subscription does not prove that a node's port is reachable, and a working node does not prove that the subscription server is currently accessible.

Refresh a Subscription Manually in Home

The steps below use the English interface on iPhone and iPad. First, make sure Home contains a subscription group, not just a few individually imported nodes. Without a subscription URL, refreshing individual nodes cannot retrieve an updated list from your provider.

1. Check the subscription

   Open Home, find the subscription group to update, and check its name and saved URL. If you have multiple groups, identify the right one so you don't mistake another subscription's results for this update.

2. Add a subscription

   If you haven't added one yet, go to the + in the top-right corner of Home → Type → Subscribe. Paste the full subscription URL from your provider, enter a name to identify it, and save.

3. Pull to refresh

   Return to Home and pull down from the top of the list to refresh the subscription. Wait for the current request to finish before continuing. Avoid repeated pulls, which can overlap requests or trigger rate limits on the server.

4. Check the list

   Check whether the group shows the expected new names or settings. If an error appears, keep its exact wording. If the list is unchanged, first ask your provider whether the remote content has actually changed.

5. Test the connection

   Select the updated node, reconnect, and visit a site that normally requires it. If needed, disconnect first and then reconnect so an existing connection doesn't skew the results.

The example subscription https://example.com/sub?token=xxxx is for illustrating URL structure only; it is not a working subscription. When copying a real link, keep everything after ? and don't add quotes, spaces, or line breaks. The token in a link is usually an access credential; don't include it in public screenshots, chat logs, or online testing tools.

Enable Update on Open

Update on Open is useful if you want the latest list when you open the app. In the English interface, the setting is usually at Settings → Subscribe → Update on Open. Layouts may vary by platform, so use the subscription settings available in your current client. Don't look for this switch in Config's rule editor.

• First, refresh manually and confirm the URL and current network work. Then enable Update on Open.
• Close and reopen the app, then check whether the subscription request completes. Switching between Home and Settings alone doesn't confirm that an update was triggered.
• If the list doesn't change after reopening, refresh it manually and check the result. This helps distinguish a request that wasn't triggered from a remote list that hasn't changed.
• Repeatedly reopening the app within a short time may result in merged requests, network delays, or server rate limits. Don't assume that every time you return to the foreground completes a download.

Update on Open is not a scheduled background task and doesn't guarantee that subscriptions will keep updating while the app is closed. It serves a different purpose from Settings → On Demand: On Demand starts a VPN connection based on connection conditions; it doesn't download subscriptions on a schedule. Adjusting On Demand to fix an outdated list usually means you're looking in the wrong place.

Subscription Update Failed: Diagnose by Error Type

An update failure doesn't necessarily mean an account has expired. DNS resolution, TLS verification, network changes, or an incompatible response can also cause failures. The messages below are examples of English errors from network requests; exact wording can vary by system and platform. Record the actual message on screen instead of just noting that the update failed.

If you receive an HTTP status code, respond according to what it means. 401 is commonly related to authentication; 403 means the server refused the request, possibly because of credentials or access restrictions; 404 means the requested path wasn't found; 429 means too many requests; and 5xx usually requires server-side investigation. Don't treat all these status codes as evidence that a node is unavailable.

• Authentication or path issue: Get a fresh link from your provider. Check whether the token was reset, the link expired, or query parameters were left out when copying it.
• Too many requests: Stop refreshing repeatedly. If the response includes Retry-After, wait as instructed before trying again.
• TLS or certificate error: Check the device's date and time, along with the network's authentication status. Don't bypass the error by turning off certificate validation.
• Server error: Note the time, network type, and status code, then report the issue to your provider. Don't repeatedly delete the existing group.

No Error, but the Node List Hasn't Changed

No error message doesn't necessarily mean valid node content was received. Some URLs return a login page, expiration notice, or network sign-in page, even with an HTTP status of 200. The client needs subscription content it can recognize, not an ordinary webpage with “subscription” in its title. Opening the link in a browser can help confirm that the URL is reachable, but it doesn't prove the app can parse it.

• Check the source: Make sure you're using the subscription URL your provider supplied for a client, not an account management or payment page.
• Check for changes: If your provider hasn't changed the list, unchanged names and counts after a refresh are expected. A matching count alone doesn't indicate an update failure.
• Check the group: Make sure you're viewing the subscription group you just refreshed, not a manually added node with the same name or an older subscription.
• Check the format: Ask your provider to confirm that the response format works with Shadowrocket. If parsing fails, keep the error message; don't overwrite Config with unrecognized content.

Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard use different settings. A subscription may include some of these protocols, but matching protocol names don't guarantee that all required settings are present. If parsing succeeds but the connection still fails, check the server address, port, authentication details, and—when using TLS—the server name. Don't rely only on whether a node appears in the subscription list.

Check Rules and Traffic Routing After an Update

Subscription updates and rule configuration are separate things to check. A change to nodes in Home doesn't update DOMAIN-SUFFIX, GEOIP, IP-CIDR, or FINAL rules in Config. Check the configuration separately only if your provider explicitly supplies a configuration file and you imported it using the appropriate method.

Proxy, Direct, Config, and Scene under Global Routing are not subscription refresh modes either. Proxy and Direct handle traffic differently, Config routes traffic according to the selected configuration, and Scene relates to scene settings. When troubleshooting, note the current selection. A successful node update doesn't mean every request will use that node.

1. Record the network, connection status, and Global Routing selection before and after refreshing. Change only one condition at a time.
2. If the subscription server can't be reached on the current network, but an existing connection can reach it, try again over that connection. Don't assume every subscription requires a connection to be established first.
3. If the update fails only after connecting, record the selected node and configuration, then check for a routing issue. Don't make long-term changes to how all traffic is handled just to refresh a subscription.
4. If a node's name changes after an update, check that policy references in your configuration and the current selection still match your expectations, then test the actual destination site.

For further troubleshooting, see the Troubleshooting Guide. To understand how Global Routing relates to rules, see Proxy Mode Guide. When reporting an issue, include the exact error, time, network type, whether a connection was enabled, and the results of manual refresh and Update on Open. Hide the full subscription URL, token, and node credentials. Keeping your working configuration is usually more helpful than deleting everything first.