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

Learn how to refresh subscriptions from Home, what Update On Open does, and how to troubleshoot expired links, network errors, and format changes.

At a glance

Added a subscription but don’t see new entries? Refresh it manually from Home, then check Update On Open under Settings → Subscribe. These steps use the English interface on iPhone and iPad and assume you already have a provider and subscription link. On other platforms, look for the same features. Learn to tell an invalid link from a network or parsing error—and why a successful update may not restore your connection.

First, know what’s being updated

A Shadowrocket subscription update fetches the saved subscription URL again, parses the response into connection entries, and syncs them to the relevant subscription group. It does not update the app or renew a service plan. Get your subscription link from your provider. Buying the client does not include a service plan, and the client’s price does not affect your provider account’s data allowance, expiration, or connection access.

Home displays connection entries and subscription groups; Config manages configuration files and their rules; Settings manages app preferences. This guide covers refreshing connection subscriptions in Home—not remotely updating a configuration file in Config. Refreshing a connection subscription usually won’t change DOMAIN-SUFFIX, IP-CIDR, or FINAL rules in Config.

2 ways
Update triggers: manual refresh in Home and Update On Open
3 areas
Check the subscription URL, network access, and response content
443
Default port for HTTPS when none is specified

Subscription URLs, connection server addresses, and configuration file URLs are different things. A subscription URL fetches entries; a connection server address and port establish the actual connection. Even if both use port 443, they may point to different servers. A successful refresh only confirms that the subscription was fetched and parsed—it doesn’t mean every connection entry works.

Refresh manually in Home

For initial troubleshooting, refresh manually so you can note when it happened, what message appeared, and whether the entries changed. First, make sure Home has a group linked to a subscription. If you only added servers manually and haven’t added a subscription URL, pulling down won’t create new subscription content. Don’t repeatedly import the same link just because a refresh showed no changes; it makes it harder to identify each group’s source.

  1. Check the group

    Open Home and find the subscription group to update. If you haven’t added one yet, tap “+” in the upper-right corner of Home → Type → Subscribe, enter the subscription URL from your provider, and save.

  2. Check the URL

    Open the subscription’s edit details and check the URL, including its scheme, path, and query parameters. Don’t use your provider account’s website login URL as the subscription URL, and remove any spaces or line breaks accidentally included when copying it.

  3. Pull to refresh

    Go back to Home, scroll the list to the top, then pull down and release. Wait for the refresh to finish. This may update multiple saved subscriptions, so check the target group rather than relying on the total number of entries.

  4. Check the result

    Note any error message, or check entries your provider has confirmed were changed. If the names and count look the same, first ask whether your provider actually changed anything; an unchanged result doesn’t necessarily mean the update failed.

The example URL https://example.com/sub?token=xxxx illustrates the URL structure only; it is not a working subscription. The token is part of the access credentials, so keeping only the domain and trying again won’t work. When sharing troubleshooting details, redact the full query string, account information, and connection credentials. Never share the original subscription URL publicly.

Update automatically on open

Turn on Update On Open under Settings → Subscribe to have the app attempt to refresh subscriptions on open, according to the feature’s trigger behavior. This is useful if you want the latest entries before using the app, but it’s not a timed refresh and doesn’t keep the app running after you close it. Background scheduling, your network, and the server response can all affect the result.

Update On Open and On Demand under Settings are separate settings. The former refreshes subscriptions; the latter starts a VPN connection when its conditions are met. Turning on On Demand won’t fix a failed subscription download, and turning it off isn’t required to update subscriptions. During troubleshooting, change only the setting relevant to the issue so you can tell what made a difference.

How a refresh works

Trigger update Request subscription URL Receive response Parse entries Sync group

The “Request subscription URL” stage requires resolving the domain, establishing a connection, and completing the TLS negotiation for HTTPS. If DNS resolution fails, the network is unreachable, or certificate validation fails, parsing can’t begin. Changing the protocol settings for a connection entry in Home usually won’t fix the subscription request itself.

Once the response is received, its content still needs to be checked. HTTP 200 only means the server returned a successful response; it doesn’t guarantee the body is a valid subscription. A provider login page, web verification page, or empty response may still download successfully. In contrast, HTTP 401, 403, and 404 can point to an access or path issue. Check the URL first instead of immediately changing DNS.

Key takeaway: identify where the process failed

For a timeout, check the network and reachability first. For 401, 403, or 404, check the provider’s link. If the request succeeds but no entries appear, inspect the response and subscription format. Troubleshooting by stage avoids changing the network, configuration, and subscription all at once.

Troubleshoot by error message

Here are common English network errors and HTTP status codes. The wording and presentation may vary with the system and interface, so note the exact message you see. A single message can narrow down the cause, but it can’t confirm by itself that an account has expired or a server is down.

Error: The request timed out.

Cause: The request didn’t finish within the time limit. The current network, access path, or subscription server response may be involved.

Fix: Stop retrying repeatedly. Try once over Wi-Fi and once over cellular. If it fails on only one network, check that network’s DNS resolution and access restrictions first.

Error: Could not connect to the server.

Cause: The client couldn’t connect to the server. The address, port, network reachability, or server status could be responsible.

Fix: Check that the URL’s domain and any explicitly specified port are intact. Then ask your provider whether the subscription service is reachable. Don’t guess at a replacement domain.

Status: HTTP 401 Unauthorized

Cause: The subscription server rejected the credentials in the request, often because the token is invalid or authorization is required again.

Fix: Get the current, complete link from your provider, replace the old subscription URL, and try again. Don’t try to fix it by changing a few characters in the parameters.

Status: HTTP 403 Forbidden

Cause: The server refused access. This may relate to account status, access restrictions, or request frequency; the status alone doesn’t mean the subscription has expired.

Fix: Stop retrying so frequently. Ask your provider to check your access permissions and any restrictions, and share the redacted error status and the time it occurred.

Status: HTTP 404 Not Found

Cause: The server couldn’t find the requested path. The URL may be incomplete, or the original subscription path may have changed.

Fix: Get the complete subscription URL again and check its path and query parameters. Don’t turn the provider’s homepage URL into a subscription URL.

For certificate errors, first check that your device’s date and time are correct, then confirm that the domain matches the one your provider gave you. Don’t hide the issue by disabling certificate validation. If other HTTPS services work but this subscription doesn’t, send your provider the domain and exact error message so they can check the certificate and service status.

Format changes and empty lists

If the network request completes but parsing fails, the group is empty, or entries are clearly missing, check whether the subscription content has changed. Your provider may have changed the output format, replaced the subscription path, or started returning an account notice page at the old path. A page opening in a browser doesn’t mean its content matches Shadowrocket’s subscription format. Don’t import a browsable HTML page as a connection subscription.

What you seeCheck firstNext step
Update succeeded, but entries are unchangedDid your provider actually publish any changes?Check for a known renamed or newly added entry; don’t rely on the total count alone.
A login or verification page appearsDid you copy the account webpage URL?Get the subscription link for use in a client from your provider.
Worked before, now parsing failsDid your provider change the format or path?Confirm the current subscription output format and keep the existing group details before changing the URL.
Only some entries are missingDid your provider remove entries or change fields?Describe the differences without sharing sensitive information and ask your provider to check the output. Don’t guess and fill in credentials manually.

Don’t make “delete and re-add the subscription” your first step. Deleting it removes the existing group you could compare against and may affect the currently selected entry. First note the subscription name, exact error message, and what changed; then decide whether to replace the URL. If you do need to add it again, confirm that the new group was created successfully and works before cleaning up duplicates.

Check the connection after updating

If websites are still unreachable after a refresh, troubleshoot the subscription separately from the connection. New entries in Home may not be selected, and the selected entry may have been removed by your provider. Select an entry that still exists in the updated subscription, then test the connection and actual access. Only then investigate DNS or rules; don’t rely on latency results alone.

  1. Check the current selection: In Home, confirm that the selected connection entry belongs to the updated subscription, not an older group with the same name.
  2. Check the routing mode: Review Global Routing. Config routes requests according to its rules, while Proxy and Direct select different overall routing modes. Refreshing a subscription doesn’t switch these modes for you.
  3. Test actual access: Check a service you normally need to reach. A latency test result doesn’t confirm that DNS, TLS, and the page request all succeeded.
  4. Prepare details for support: Note the network type, time of the issue, exact error message, and which stage failed. Hide tokens, passwords, and the complete subscription URL before contacting your provider.

For everyday use, you can leave Update On Open enabled for convenient updates and manually refresh after your provider announces changes. If updates keep failing, check the URL, network reachability, and response format in that order; it’s more targeted than repeatedly reinstalling the app. Shadowrocket does not provide, sell, or recommend servers or subscriptions. This guide assumes you already have your own provider and subscription.

Download Shadowrocket