This guide is for Shadowrocket users who already have their own subscription URL. First, refresh it manually from Home and confirm the URL returns valid content. Then go to Settings → Subscribe and enable Update on Open. If the update fails, check the URL, request route, and response format in that order. Subscription updates and server connection tests are separate tasks. Keeping your existing configuration usually makes troubleshooting easier than deleting it and importing it again.
1. Subscription Updates vs. Connection Failures
A subscription update sends a request to an existing subscription URL and parses the response into server entries. It does not test whether each server is reachable or update routing rules in Config. Entries in Home may connect even if the subscription URL is no longer valid. Likewise, a successful subscription update does not guarantee that every entry will work on your current network.
Before you begin, keep any entries and configurations that still work, and note the exact error message. Don't delete the entire subscription group because of a single timeout. If your existing entries still connect, they may also provide a working network route for the subscription request.
- Home: View existing subscriptions and server entries, refresh them, and check for changes.
- Settings → Subscribe: Configure subscription updates, including Update on Open and Update via Proxy.
- Config: Manage configurations and rules. Refreshing a server subscription does not update the configuration file here.
- Settings → On Demand: Configure when connections are established. This is not where you schedule subscription updates.
Shadowrocket is a paid client for Apple platforms and is available exclusively through the App Store. Purchasing the app does not include a server subscription. This guide explains how to manage a subscription you already have; it does not provide, sell, or recommend subscriptions or related services.
2. Manually Refresh an Existing Subscription in Home
Start with a manual refresh you can observe, then enable automatic updates. This helps distinguish a failed request from an update that never triggered, without changing several settings at once.
-
Check the subscription
Open Home, find the subscription group you want to refresh, and check its name and saved URL. If you have multiple groups, identify which one produced the error. New entries appearing in another group do not mean this one updated successfully.
-
Check the URL
Make sure the URL is complete, especially any parameters after the question mark. Added line breaks or spaces, or a missing part of a token, can cause the same domain to return different results.
-
Pull to refresh
Pull down in the Home list to refresh the subscription, then wait for the request to finish. If you have multiple subscriptions, check each group separately. Avoid repeated pulls that could obscure the first error message.
-
Check the result
Check whether the error is gone, the group still contains entries, and names, regions, or counts have changed as expected. The content may be unchanged even when the update succeeds, so an unchanged count alone does not indicate failure.
If you haven't saved the subscription yet, go to Home, tap “+” in the upper-right corner, select Type → Subscribe, then enter and save a URL you already have. Adding it again isn't the first thing to try when an existing subscription fails to update. Check that the original URL is still valid first to avoid duplicate groups pointing to the same address.
https://example.com/sub?token=xxxxThe address below is entirely fictional and cannot be used for import. A token in a real subscription URL often acts as an access credential. Don't share the full URL in public logs, screenshots, or website files.
3. Set Up Update on Open and Choose a Request Route
Go to Settings → Subscribe, find Update on Open, and turn it on. This triggers a subscription update when you open the app; it does not mean the app stays active in the background or polls at a fixed interval. If the app remains in the foreground, don't assume something is wrong just because it hasn't refreshed again. To get the latest content right away, refresh manually from Home.
| Setting or action | What it controls | When to use it |
|---|---|---|
| Pull to refresh in Home | Starts a subscription update on demand | Check whether the URL works over the current request route |
| Settings → Subscribe → Update on Open | Update on Open | Verify automatic updates after a manual refresh succeeds |
| Settings → Subscribe → Update via Proxy | Update via Proxy | Compare results when the subscription URL is unreachable over a direct connection |
| Settings → On Demand | On Demand | Check connection behavior; it does not replace subscription update settings |
Bottom line: Verify the request route before enabling automatic updates
If a manual refresh hasn't succeeded, turning on Update on Open will only repeat the same failed request. First get one manual refresh to work, then check whether the subscription updates when you reopen the app.
Before enabling Update via Proxy, confirm that your existing proxy connection works, then try a manual refresh. A dependency loop can occur if the subscription request needs a proxy, but the proxy needs new entries that are only available from that subscription. In that case, keep any working old entries or test again on another network that can reach the URL.
Config, Proxy, Direct, and Scene in Global Routing control how connections are handled; they don't set the subscription update frequency. Don't switch routing modes, change rules, and rebuild your configuration just to fix one subscription error. Test the effect of Update via Proxy on this request by itself so you can identify what changed.
4. Troubleshoot URL, Network, and Response Errors
The following are error messages or HTTP status codes that may appear during a network request. The app may show an address, an error domain, or other context. Save the full error as it appears; it may not match the examples below exactly.
Error: 401 Unauthorized
Cause and solution: The server didn't accept the authentication information sent with the request. Check that all URL parameters are present, then ask the provider of your existing subscription to confirm the credentials are still valid. If the URL has been reset, replace the saved URL instead of repeatedly refreshing the old one.
Error: 403 Forbidden
Cause and solution: The server refused the request, possibly because of access policies, credential status, or restrictions on the request source. First confirm that you're authorized to access the subscription, then check the subscription URL and requirements provided by its service. A 403 alone doesn't mean the app failed to parse the response.
Error: 404 Not Found
Cause and solution: The requested path doesn't exist, or the server is using this status to hide an inaccessible resource. Check the URL path and parameters, and make sure the full address was copied. Confirm that you haven't used an account page URL or an old, deactivated subscription URL by mistake.
Error: The request timed out.
Cause and solution: The request didn't finish in time. The issue may have occurred while resolving the address, establishing a connection, or waiting for a response. First compare Wi-Fi and cellular networks. Then, if you have a working connection, test Update via Proxy.
An HTTP status can narrow down the cause, but it can't prove on its own that a subscription has expired. For example, a 403 may come from the origin server or from an access control in between. When checking, note the network type, whether you're using a proxy, and the result from trying the same URL on another network. For certificate errors, check that your device's date, time, and URL are correct. Don't bypass certificate checks as a substitute for troubleshooting.
5. The URL Opens, but Why Won't the Subscription Import?
A page that opens in a browser only means that you received some kind of response; it doesn't mean that the response is a subscription. The browser may show a login page, an access verification page, or an error message. Even an HTTP 200 response may contain HTML. Shadowrocket needs recognizable subscription content, not a webpage that can be read in a browser.
- Login page returned: Check that you copied the subscription URL for importing into a client, not an account management page. Being logged in through your browser doesn't mean the app's request includes the same session information.
- Verification page returned: Passing an interactive check in a browser doesn't mean a subscription request can pass it automatically. Ask the provider of your existing subscription which URL to use for client subscriptions.
- Empty response returned: Check the account and subscription status, confirm that valid entries exist, and distinguish a genuinely empty response from a page that hasn't finished loading.
- Unsupported response format: Confirm that the response is subscription content compatible with Shadowrocket. Don't enter a complete routing configuration, general explanatory text, or data intended for another purpose in Subscribe.
Protocol names and subscription formats are different things. Seeing Shadowsocks, VMess, VLESS, Trojan, Hysteria2, or WireGuard in the content doesn't guarantee that the current import screen can parse the entire response. Check that its structure and fields are supported.
Keep the subscription URL fixed and compare two networks. Then keep the network fixed and compare results with and without Update via Proxy. Record each result before changing the next setting. Avoid changing the URL, clearing the group, modifying DNS, and rewriting rules all at once; otherwise, it's hard to tell what made a difference.
6. Common Questions About Automatic Updates and Refresh Results
Manual refresh works, but why don't I see any changes when I open the app?
Go to Settings → Subscribe and make sure Update on Open is enabled. Then leave the app, reopen it, and check for an update. An unchanged server list doesn't mean no request was made: if the remote content is the same, the names and count may not change at all.
A subscription update timed out. Should I turn on the connection first?
Not necessarily. If the URL is reachable directly, try refreshing it directly first. Only establish a working connection before checking Update via Proxy in Settings → Subscribe if the request needs a proxy route. Turning on the connection doesn't guarantee that the selected entry works.
The update succeeded. Why won't the webpage open?
First, check the selected server and connection status in Home, then check Global Routing and Config. A subscription refresh only retrieves and parses the server list. Opening a webpage also depends on the selected server, DNS, and rules. Don't treat a subsequent connection problem as a subscription update failure.
Does On Demand update subscriptions on a schedule?
On Demand controls when connections are triggered; it doesn't refresh subscriptions at fixed intervals. To update when you open the app, check Settings → Subscribe → Update on Open. To update right away, manually refresh in Home.
What information should I keep if troubleshooting still fails?
Note the exact error message, when it occurred, whether you were on Wi-Fi or cellular, the Update via Proxy setting, and whether your old entries still connect. Before sharing details, hide the full URL, token, account name, and password. This information is enough to help identify which part of the request failed; don't publish access credentials.
Once the issue is resolved, keep one verified update route. To check the initial import and authorization steps, read the user guide. To understand the difference between subscription and configuration management, see the subscription manual. Refreshing a subscription doesn't change the app's purchase status. Check the App Store listing for system requirements and device compatibility.