If you already have your own service details and subscription URL, start by refreshing manually in Home. Check whether the problem is URL access, response parsing, or server connectivity, then go to Settings → Subscribe and configure Update on Open. This guide explains the differences between a one-time refresh, automatic updates on launch, and Update via Proxy. If an update fails, keep the existing list instead of deleting and recreating it right away.
First, distinguish subscription updates from server connections
A Shadowrocket subscription update requests content from a saved subscription URL and adds any server details it can parse to the list. The connection switch in Home uses the currently selected server to establish a connection. These are separate processes: a server that still works does not mean its subscription URL is still valid, and a successful subscription fetch does not mean every server in the response can connect.
This guide assumes you already have your own subscription. Before troubleshooting, note the subscription group name, the exact error, when it occurred, and your current network type. If you have edited individual entries, save any information you need first. A refresh may rebuild entries based on the remote content, so manual edits are not guaranteed to persist.
This refers to the HTTPS request port used by the subscription URL, not a server connection port. For example, a subscription URL using the default HTTPS port, 443, can still list servers on other ports specified in their service details. Don't change every server port to 443 just because a subscription update failed.
Refresh subscriptions manually in Home
A manual refresh is useful for verifying an initial import or checking for changes to your service details. Review the full result before deciding what to try next, and don't pull to refresh repeatedly in quick succession. Frequent requests may trigger rate limits on the subscription service and make it harder to tell which error came from which attempt.
-
Check the entry
Open Home and confirm that a Subscribe-type subscription and its group are listed. If you only added a server manually, there is no subscription URL to refresh the group from.
-
Check the URL
Open the subscription's edit details and make sure the URL is complete. Don't use an account login page, purchase history page, or individual server share URI as a subscription URL. Never show the full token in screenshots or public posts.
-
Pull to refresh
Return to Home, pull down on the list to refresh, and wait for the request to finish. If you have multiple subscriptions, check each group separately; a change in one group doesn't mean every subscription updated successfully.
-
Check the result
Review any messages, the group contents, and the expected changes. An unchanged server count doesn't necessarily mean the update failed—the remote content may be identical. Likewise, changes to the list don't replace a connection test; select the server you intend to use and verify access.
Automatic updates on launch: Update on Open
After a successful manual refresh, go to Settings → Subscribe → Update on Open and enable updates when the app opens. This setting triggers a subscription update on launch; it does not continuously poll servers or hand the task to a background timer that guarantees an exact schedule.
For your first test, refresh manually and confirm it succeeds before enabling Update on Open. Close and reopen the app, then check the result. Simply returning to Home from another screen isn't a reliable way to confirm that an update-on-open was triggered. Network availability and the app's state can also affect whether the request completes.
- Open the app often: You can enable Update on Open to reduce the chance of forgetting a manual refresh, but still check for error messages after opening the app.
- Your network requires a web login: Complete the Wi-Fi sign-in first, then refresh. Otherwise, the authentication page may be mistaken for a subscription response.
- Haven't opened the app in a while: Don't assume the list has been syncing in the background. When you need it, open Home and refresh manually to check.
- The remote service limits request frequency: Avoid repeatedly closing and reopening the app or refreshing in quick succession. Wait as directed by your service information before trying again.
Settings → On Demand manages connection triggers; it is separate from subscription updates. Enabling On Demand does not enable Update on Open, and disabling updates on launch does not turn off existing connection triggers. Track these settings separately while troubleshooting so you can identify the cause.
Timeouts and network restrictions: when to use Update via Proxy
First confirm that your current network works, then check whether the subscription domain is reachable through the current route. If regular websites won't load either, address Wi-Fi authentication, cellular data permissions, or network switching first. If only the subscription request times out, investigate the request route instead of replacing the URL right away.
If the subscription URL is unreachable over your current direct connection but an existing server still works, connect first. Then go to Settings → Subscribe → Update via Proxy, enable the option, and manually refresh in Home. This changes how subscription update requests are routed; it cannot fix expired credentials, an incorrect URL, or an incompatible response.
| What you observe | What to try first | What this does—and doesn't—tell you |
|---|---|---|
| Both regular websites and subscription requests time out | Check your network, switch between Wi-Fi and cellular, then try again | You can't yet conclude that the subscription URL has expired |
| Direct request fails, but an existing connection works | Connect, then test Update via Proxy | Success only confirms that this request route worked |
| Still returns 401 over an existing connection | Check your subscription credentials with your service provider | Changing the network route usually won't fix credentials |
| None of your existing servers work | Check your basic network connection and the subscription service status first | You can't rely on a nonworking connection to update through a proxy |
Takeaway: change one thing at a time
Keep the same subscription URL. First switch the underlying network and test once, then test Update via Proxy separately. Record each result, and avoid changing the URL, connection mode, and update settings all at once.
Home → Global Routing offers Proxy, Direct, Config, and Scene for choosing how traffic is handled; they are not four subscription formats. In Config mode, rules such as DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL affect how matching traffic is routed, but adding rules at random won't make an expired token valid again. When checking rules, first identify the route used for the request.
Use the error message to distinguish an expired URL from a format issue
The messages below are examples you may see in network responses or system errors. The interface may show only a status code, a brief description, or a localized message, so use the details recorded for your own attempt. A status code can help identify the type of problem, but it alone cannot prove that an account has expired or a server is permanently offline.
Error: 401 Unauthorized
Cause: The request did not include credentials accepted by the subscription service. The token in the URL may be missing, expired, or reset.
What to do: Check the current subscription URL in your own service account, copy it in full, replace the old URL, and refresh manually. Don't copy only the part before the question mark.
Error: 403 Forbidden
Cause: The subscription service rejected the request. This may involve account permissions, the request's source, or server-side policies.
What to do: Note when it happened and the status code, then check the access requirements with your service provider. Trying a different route can help isolate the issue, but it won't necessarily remove an access restriction.
Error: 404 Not Found
Cause: The requested path doesn't exist. Common reasons include a retired endpoint, an incomplete URL, or an accidentally changed path.
What to do: Check the domain, path, and query parameters. Use the current subscription URL from your own account; don't guess a new path.
Error: The request timed out.
Cause: The request didn't complete in time. The issue may be with the network connection, the subscription service's response, or an intermediary route.
What to do: Check that your network works, then test a network switch and Update via Proxy separately as described above. Don't assume a timeout means the URL has expired.
Another possibility is that the HTTP request completed but the response couldn't be parsed. A 200 status means the request succeeded at the HTTP level; it does not guarantee that the body is a valid subscription. A login page, network authentication page, service maintenance notice, or HTML error page may also be returned with a 200 status.
- Login page returned: Make sure you copied the subscription endpoint, not an account management page that requires browser sign-in. A subscription request can't reuse your browser's login session.
- Empty response: Check that your account currently has content available and that the subscription service isn't temporarily down. Adding the same URL again won't restore missing content.
- Response doesn't match the intended use: A single Shadowsocks, VMess, VLESS, or Trojan share URI is not the same as a subscription URL for fetching a list of servers.
- Certificate warning: Check your device's date and time and the subscription service's certificate status. Don't disable security checks or install certificates from unknown sources just to get a refresh to work.
Check the URL for completeness and protect sensitive information
A subscription URL often also serves as an access credential. The domain and token below are examples only and won't work as an actual subscription. You can compare the structure with your own URL while troubleshooting, but don't post the real link on public pages or in screenshots.
https://example.com/sub?token=xxxx- Keep query parameters:
?token=xxxxis not a disposable note. Keep any other parameters in the actual URL as well. - Remove extra characters: Check for spaces, line breaks, curly quotation marks, or chat text at either end. Don't paste explanatory text into the URL field.
- Keep the original encoding: Don't manually change percent-encoding in the URL or truncate parameters after
&. Use the URL exactly as copied. - Replace a leaked token: Reset your subscription credentials in your own service account, then update the old URL in Shadowrocket.
Troubleshooting notes usually need only the group name, time, network type, exact error, and whether Update via Proxy was enabled. If you contact your service provider, use its existing support channel and share redacted details first. Whether it can access request logs depends on its actual capabilities.
FAQ: subscription updates and automatic refresh behavior
Why does the list still look old after I enabled automatic updates?
First, manually refresh in Home to see whether the request succeeds, then check Update on Open under Settings → Subscribe. If manual refresh also fails, troubleshoot the URL or network error. If the remote service returns the same content, the list may look unchanged even after a successful update.
Why can't I use the selected server even though the subscription updated?
An update only confirms that the subscription content was fetched and parsed. Return to Home, check your selection and Global Routing settings, and verify the service details before testing access. A successful update does not mean every server is usable.
Should I delete and re-add the subscription after an update fails?
Keep the existing entry for now and check the URL and exact error. Deleting it removes useful information for comparison and won't fix a timeout or permission issue. If you need to replace the URL, note the group and any necessary settings first, then edit the existing subscription to avoid duplicate lists from repeated imports.
What should I do if only one of several subscriptions fails to update?
Check the URL and response status for the affected group on its own. Other subscriptions working only shows that some requests are reachable; it doesn't prove that this domain, path, and token are valid. Don't change every group's settings as a result.
Does buying Shadowrocket automatically include a subscription?
Buying the app does not include a service plan. Shadowrocket is a closed-source commercial app available on the App Store. Subscription content comes from service information you already have, so check the app purchase and subscription URL separately.