Shadowrocket Subscription Update Failed? Manual Refresh & Update on Open

Learn how to refresh a subscription manually, enable Update on Open, and troubleshoot common failures caused by expired links, network issues, or format changes.

At a glance

When a Shadowrocket subscription update fails, keep your existing entries, try a manual refresh, note the message, then check the URL, network path, and response format. This guide assumes you already have a provider and subscription. It covers refreshing from Home, the automatic update setting under Settings → Subscribe, and how to distinguish a subscription update failure from a server connection failure. The steps use the iPhone / iPad interface; menu locations may vary on other platforms.

First, distinguish subscription updates from connection tests

A subscription update sends a request to the subscription URL and parses the response into server entries. A connection test uses the address, port, and protocol settings of an existing entry to establish a connection. These are separate checks. A working existing server does not mean the subscription URL is still valid, and a successful refresh does not mean every server in the list can connect.

Home shows server entries and connection status; Config is mainly for managing rule configuration files. Do not confuse updating a remote configuration in Config with updating a server subscription in Home. Before troubleshooting, identify which item failed so you do not replace an entire rule file to fix a subscription.

Two different operations
Subscription updates retrieve the list; connection tests check existing entries. Each tests something different.
443
The default port used by HTTPS when no port is specified. It is not the server port.

Manually refresh a subscription in Home

Start troubleshooting with a manual refresh so you can see the result directly. Do not delete the subscription first: existing entries may still connect, and deleting them could leave you without anything to test if you cannot retrieve the list again. Note the subscription group name, current entry count, and error message before following these steps.

  1. Identify the group

    Open Home and find the subscription group you need to refresh. If you have multiple subscriptions, confirm which one you are checking; changes in another group do not mean this update succeeded.

  2. Check the URL

    Open the subscription’s edit screen and make sure the URL is complete. To add one for the first time, go to Home → “+” in the top-right corner → Type → Subscribe. If the entry already exists, edit it instead of creating a duplicate.

  3. Pull to refresh

    Return to Home, pull down from the top of the list, and release to refresh the subscription. Wait for the request to finish, then read the success or error message. Repeated refreshes may increase the chance of rate limiting.

  4. Check the result

    Check whether the target group still has entries and whether its name and count look as expected. If the refresh succeeds but the count stays the same, the remote content may simply be unchanged; the count alone does not indicate failure.

If the list becomes empty after an update, stop refreshing. Note the message and ask your provider whether the subscription returned an empty list or whether the available entries changed. Adding the same URL again will not fix an issue with the remote content.

Enable Update on Open

Go to Settings → Subscribe, find Update on Open, and turn it on. This setting attempts to refresh subscriptions when the app opens, and is best used after you have confirmed that manual updates work. Leave the app, open it again, and check the result. Switching between Home and Config alone is not a reliable way to verify automatic updates.

If updates fail only when you reopen the app but succeed after waiting a few seconds and refreshing manually, check whether the device has finished connecting after switching between Wi-Fi and mobile data. Temporarily turn off Update on Open, wait for the network to stabilize, then try a manual refresh to distinguish a startup timing issue from a URL problem.

Check the URL and access permissions based on the error

Error messages vary with the system language, network layer, and server response. The examples below explain common messages and status codes; you may not see exactly the same wording every time. Recording the original message is more useful than simply noting “update failed.”

Error: The request timed out.

Cause: The request did not finish within the allowed time. The connection may be unavailable, the remote server may be slow to respond, or the proxy path may not work.

Try this: Switch between Wi-Fi and mobile data, then test direct and Update via Proxy paths separately. Change one setting at a time.

Error: A server with the specified hostname could not be found.

Cause: The subscription hostname could not be resolved. The domain may be misspelled, DNS may be failing, or the domain may no longer be active.

Try this: Check the full domain name and try another network. If the problem persists, ask your provider to confirm the current subscription domain.

Status code: HTTP 403

Cause: The server refused access. This may be related to the URL token, account permissions, or restrictions on the request source.

Try this: Check the subscription status and latest URL in your own service account. Reinstalling the app repeatedly is not a troubleshooting step.

Status code: HTTP 429

Cause: The server is limiting requests made in a short period. Automatic refreshes from multiple devices may also trigger the limit.

Try this: Stop refreshing repeatedly, wait as directed by the server, and reduce duplicate requests from other devices.

Subscription URLs often contain account credentials. When checking one, make sure the parameters after the question mark are complete, that there are no spaces or line breaks, and that the URL was not truncated by a messaging app. The example below is for identifying the URL structure only, not a working subscription address. Hide the actual token when sharing troubleshooting details.

https://example.com/sub?token=xxxx

Check the update request path when the network is unavailable

Being able to open regular webpages does not prove that the subscription domain is reachable. Different domains may use different DNS results, access restrictions, or network paths. Keep the current settings and refresh the same subscription over another network. If it fails only on one network, troubleshoot that network rather than immediately changing every server setting.

  1. Note the current setting for Settings → Subscribe → Update via Proxy, then refresh once without changing it and record the result.
  2. If direct updates fail but an existing server still connects, select a confirmed working entry in Home and connect through it. Then enable Update via Proxy and try again.
  3. If updates through the proxy fail, turn off Update via Proxy and test a direct connection. Do not assume that using a proxy will always work better than connecting directly.
  4. Check whether Global Routing is set to Proxy, Direct, Config, or Scene, and note the mode used for this test. An enabled connection toggle alone does not prove that every request goes through a proxy.
  5. If you see a certificate or secure connection error, check that the device’s date, time, and time zone are correct. Do not bypass verification by ignoring certificate errors.

When using Config, rules may affect where the request goes. Do not add broad DIRECT or PROXY rules just to test a subscription. Make small, reversible changes to identify the cause before deciding whether to adjust the configuration.

Request succeeds but parsing fails: check the response format

A successful HTTP request only means a response was received; it does not guarantee that the response is a valid subscription. The server may return a login page, access instructions, a verification page, or empty text, sometimes with HTTP 200. Repeatedly tapping Update will not turn a webpage into a server list.

What you seeCheck firstWhat to do
Parsing fails after the request completesWhether the URL is a client subscription, not an account management webpageCopy the correct subscription URL again from your service account, then edit the existing entry.
It worked before, but failed after a format changeWhether the server changed the output format or added unsupported fieldsTell your provider you use Shadowrocket and share a redacted error message to confirm a compatible format.
Update succeeds, but the number of entries dropsWhether the remote server deleted entries, changed account permissions, or returned an empty listCheck your account status and the remote content first. Do not assume the problem is a local parsing error.
The list looks normal, but servers cannot connectServer address, port, protocol settings, and whether the entry is still validSwitch to connection troubleshooting instead of repeatedly refreshing the same list.

Do not copy an entire error page into Add Server. Shadowsocks, VMess, VLESS, Trojan, and other entries have their own fields; subscription parsing and manual entry are different operations. If you need to enter details manually, get the exact settings from your provider rather than guessing the protocol or port based on webpage text.

Frequently asked questions and troubleshooting notes

Why did the update fail if my old servers still work?

The subscription URL and server address are different request targets. Keep your existing entries, test a connection from Home, then check the subscription URL’s permissions and network path separately. Do not delete the entire group first.

Why is my list still old with automatic updates enabled?

First, pull down to refresh in Home and read the message, then check Settings → Subscribe → Update on Open. If the request succeeds but the list does not change, confirm that the server has actually published new content. An unchanged name and entry count do not, by themselves, mean automatic updates failed.

Will copying the old URL definitely work after I get a new phone?

Not necessarily. The URL may have been reset, or access may be limited by account permissions or request frequency. Confirm it is still valid in your service account, then add it via Home → “+” → Type → Subscribe. Do not post a complete URL containing a token in a public discussion forum.

Should I reinstall Shadowrocket after an update fails?

Do not reinstall it yet. Save your configuration and subscription entries, then test another network, check the URL, and switch the update path. Consider further steps only if you have identified a local app state issue. Reinstalling will not change a server’s refusal to grant access.

When contacting your provider, include the failure time and time zone, network type, exact error message, whether Update via Proxy was enabled, and what happened on another network. Send account or URL details only through the provider’s private support channel. This site does not provide, sell, or recommend servers, subscriptions, or VPN services; it covers client settings and troubleshooting only.

Download Shadowrocket