At a glance

This guide is for users who already have a subscription URL from their own service provider. First, pull down on Home to refresh manually, then check Settings → Subscribe → Update on Open. If an update fails, check the link, network request, and response format in that order. After a successful refresh, verify the server list, selected server, and connection separately—a refresh animation alone does not confirm success.

What a subscription update changes

A Subscribe entry in Shadowrocket stores a subscription URL. When you refresh it, the app requests that URL, reads the server data returned by the provider, and updates the associated group. This does not update the app itself or renew your service plan. The steps below use the iPhone / iPad interface; on other platforms, look for the corresponding options in the interface.

Read the subscription URL Request remote content Parse server data Update the associated group Check the connection

The server list in Home, rule configurations in Config, and app preferences in Settings are separate layers. A successful subscription update usually means that the server data was fetched and parsed; it does not mean that a rule file in Config was also updated. Servers added individually are not automatically included in a subscription when another subscription refreshes.

3 locations
View the list in Home, manage configurations in Config, and adjust update behavior in Settings
2 triggers
Test pull-to-refresh and Update on Open separately
3 checks
Link validity, network reachability, and response format

Manually refresh from Home

Start troubleshooting with a manual refresh. It gives you a clear trigger time and makes it easier to match any on-screen error to that request. Don’t delete the entire group after the first failure. Keep the existing entry and error details so you don’t also lose track of the server currently in use.

  1. Check the subscription entry

    Go to Home and find the Subscribe entry you want to update. Open its edit screen, confirm that Type is set to Subscribe, and check that the URL matches the current address from your service provider.

  2. Add an entry if needed

    If you have only manually added servers and no subscription entry, tap “+” in the upper-right corner of Home, set Type to Subscribe, paste your subscription URL into URL, and save. Skip this step if you already have an entry.

  3. Pull down to refresh

    Return to Home, pull down from the top of the list, and release. Wait for the refresh to finish. If you have multiple subscriptions, check each one separately; success for one does not mean they all updated.

  4. Check the results

    Review the server names and entries under the target subscription. An unchanged list may mean the remote content hasn’t changed. If an error appears, note its exact text rather than simply writing “update failed.”

  5. Test the connection

    Check the dot next to the selected server again, connect if needed, then run Connectivity Test. Fetching the list successfully and connecting to a server are separate results.

Turn on Update on Open

Go to Settings → Subscribe → Update on Open and turn on updates when the app opens. Then open the app normally and check whether the subscription refreshes. Settings may be arranged differently across platforms, so look for the option by name. This setting isn’t in Config.

Settings → On Demand controls when connections start based on conditions; it does not schedule subscription updates. Don’t keep changing On Demand to make subscriptions refresh automatically. If manual updates work but Update on Open doesn’t, first confirm that Update on Open is still enabled, then note the network status when you open the app.

Read the exact error before choosing what to try

“Update failed” can point to problems at different stages. The cards below show common error messages and HTTP status codes. The exact wording may depend on the system and server, so use the complete message shown on screen rather than assuming every failure means the link has expired.

Error: Failed to load subscription

What it means and what to do: This is a general subscription loading error; it doesn’t confirm whether the link expired or the format is invalid. Check the full URL, then look for a more specific network or HTTP error from the same request.

Error: The request timed out.

What it means and what to do: The request didn’t finish in time. The cause may be your local network, the remote server, or the request route. First check that you can access the internet, then try the same URL once on Wi-Fi and once on cellular data.

Response status: HTTP 401

What it means and what to do: The server requires valid credentials. The token in the URL may be missing, expired, or reset. Get the current subscription URL from your service provider, replace the entire URL, and try again.

Response status: HTTP 403

What it means and what to do: The server refused the request, possibly because of account permissions or access policies. Send your service provider the status code and time of the error; this status alone doesn’t prove that your plan has expired.

Response status: HTTP 429

What it means and what to do: The server is limiting requests because they’re coming too often. Stop refreshing repeatedly and wait as your service provider advises. If the response includes Retry-After, follow that instruction.

Change one thing at a time while troubleshooting. For example, keep the subscription URL unchanged and switch networks first. On the next attempt, keep the network the same and try a new URL from your service provider. Otherwise, even if the update works, you won’t know which change fixed it.

Expired links, network errors, and unsupported formats

Check the link: verify the full URL and account status

The token in a subscription URL is usually used for authentication. Leaving out parameters after the question mark, or adding an extra space or line break, can make a request fail. If your service provider reset the link, the old URL may stop working immediately. Confirm that the link is still valid and that your account can access the subscription.

Check network reachability: distinguish DNS, connection, and certificate errors

An HTTPS subscription URL without an explicit port usually connects over TCP 443. DNS lookup failures, connection timeouts, and TLS certificate validation errors are different problems. Being able to open other websites only confirms that some network access works; it doesn’t prove that the subscription domain is reachable.

Proxy, Direct, Config, and Scene under Home → Global Routing affect how connections and traffic routing work, but don’t assume they determine the route used for every subscription request. Switching between Proxy and Direct also changes the traffic path for other apps. Note the current mode and VPN status while troubleshooting; don’t leave the app in a different mode just to refresh a subscription.

Unsupported formats: a successful response may still be unusable

An HTTP 200 response means the HTTP request succeeded, but it doesn’t guarantee that the response body is a valid subscription. The server may return a login page, maintenance notice, or empty body. Even recognized subscription data may not produce usable entries if required fields are missing or protocol parameters are incomplete.

What you seeCheck firstNext step
The response is an HTML pageWas a login or verification page returned?Ask your service provider for the subscription URL to use with Shadowrocket
The response or server list is emptyHas the account been assigned server data?Ask your service provider to check the response; don’t delete the existing group
Some entries won’t importAre the required fields for that protocol complete?Send a redacted error and the protocol type; don’t guess at the parameters
Names and server count haven’t changedHas the remote list actually been updated?Confirm the request succeeded, then ask your service provider about the expected content

If the update succeeds but you still can’t connect

A successful update doesn’t mean every server is reachable. If the remote list removed or replaced an entry, check the selected server again. For VMess, VLESS, Trojan, and other entries, the address, port, UUID or password, transport, and TLS settings must come from your service provider. Don’t fill in values at random to clear an error.

  1. In Home, confirm that the selected server is the updated entry—not a manually added entry with the same name.
  2. Connect, then run Connectivity Test to tell whether the subscription can be fetched and the server can be reached.
  3. If the test succeeds but a particular domain still has a problem, check the current Global Routing mode and which Config rules match.
  4. When checking rules such as DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL, change only settings related to the issue. Editing rules won’t fix an unsupported subscription format.

When contacting your service provider, include the time of the error, the local network you used, the exact error message, and the results of manual and on-open updates. Redact tokens, UUIDs, and passwords from subscription URLs. Don’t share a full URL in public screenshots or comments. If it has already been exposed, reset the link with your service provider and update the URL in the app.