Official Guide · Setup Tutorial
Shadowrocket Setup Guide Import Subscriptions and Check Connections
Follow this order: prepare details → import → choose a routing mode → connect → verify. Start with one server to confirm the full process, then organize subscriptions and rules. Avoid changing multiple settings at once.
If this is your first time, start with Step 1. If your list is already present but you cannot access pages, go to Step 4 to check the symptoms, then use Step 5 to troubleshoot. Avoid deleting existing configurations for now.
STEP 01 / IMPORT
Add a server or import an existing subscription
First identify what you have: a subscription URL used to update a server list, or the address, port, and authentication details for a single server. These details go in different places; do not enter a subscription URL in the server address field. After opening Shadowrocket, go to Home and check the existing list. If a group from the same source is already there, decide whether to update that group first to avoid duplicate entries.
Have a subscription URL? Choose Subscribe in Add Server
On Home, tap the add button in the upper-right corner to open Add Server. Open the Type selector and choose Subscribe, then paste the complete subscription URL into the URL field. Give it a name that is easy for you to recognize, then save and return to Home while the subscription loads. The name is for identification only and does not change the connection details associated with the subscription.
Before pasting, check that the URL is complete, especially that its ending parameters have not been split across lines, truncated, or followed by spaces by a messaging app. Subscription URLs usually contain personal access credentials. Two URLs are not necessarily equivalent just because they share a domain. If you need to retrieve the URL again, get the complete one from your own service provider. Do not combine it with parameters supplied by someone else or submit it to an unfamiliar website for testing.
After returning to Home, you should see a group and its server entries. If only the group name appears, check for a subscription update error first, then check whether the current network can retrieve the subscription details. A failed subscription update and a failed connection to an individual server are separate issues: the first means the list has not been retrieved; the second means a connection could not be established using details already in the list. Keep these stages separate when troubleshooting.
Have details for one server? Check Type and each parameter
If you have details for an individual server, also start from Add Server, but choose the protocol specified in your details for Type rather than Subscribe. Enter the server address, port, and authentication details as provided. Fields vary by protocol. Use your server's actual configuration for passwords, encryption methods, and other connection parameters; do not replace them with example values from another guide.
Fill in additional transport and TLS options only when your details explicitly require them. Domains, paths, and other fields may be case-sensitive, and omitting one field can cause a connection failure. If you have an importable QR code, you can use the app's Scan QR Code feature. After importing, open the entry and check that its protocol and address are as expected. A QR code is only a way to carry details; it does not prove that the server is working.
After saving, return to Home and tap the server you plan to use to make it the current selection. Keep one clear test target and avoid switching servers at random before each test. At this point, you have only added connection details to the app. You still need to choose how traffic is handled and establish the system connection.
STEP 02 / GLOBAL ROUTING
Choose a Global Routing mode
Open Global Routing from Home. This setting determines how traffic is handled; it is separate from the server currently selected. For your first test, check the selected server, then choose Config / Proxy / Direct for your purpose. After making a selection, return to Home and check the active state rather than leaving the setting on its selection screen.
Config: Apply the rules in the current configuration
Config determines where requests go based on the configuration currently in use. Rules may send some requests to PROXY, others to DIRECT, or use REJECT. Selecting a server does not mean that every request will pass through it. If you already have a trusted configuration that suits your current environment, first check which one is enabled in Config, then return to Global Routing and select Config.
Do not confuse subscriptions with configurations: Subscribe is mainly for retrieving and updating server details, while Config contains settings such as rules. Importing a subscription does not mean that you have imported a set of traffic-routing rules suited to your needs. You do not need to edit DOMAIN-SUFFIX, GEOIP, or FINAL for an initial check. First confirm which configuration is active and what it is for. For complex rule issues, see the FAQs about traffic routing.
Proxy: Compare results when checking the proxy connection
If you are unsure whether rules failed to match or the current server is unavailable, temporarily select Proxy and run a comparison using the same server and test page. Proxy applies traffic using the proxy mode, but this does not mean all system traffic will necessarily follow the same route. If access works under Proxy but fails under Config, focus on the current configuration, matching strategy, and name resolution rather than deleting the subscription immediately.
Direct: Check the direct access path
Direct handles traffic using a direct connection and is not suitable for verifying whether a proxy server works. It can be part of a basic network check, but it is not exactly the same as turning off the system connection. After testing, return to Global Routing and restore the mode you need. Note the current setting; for every later test, specify whether it was done with Config, Proxy, or Direct.
STEP 03 / CONNECT
Turn on the connection and authorize it in the system
Return to Home, confirm the selected server and current Global Routing mode, then turn on the connection switch at the top. The first time you connect, the system may ask for permission to add a VPN configuration. Confirm that the prompt appeared after you initiated a connection in Shadowrocket, then allow it and authenticate with a passcode or biometric method as required by your device. This authorization adds the configuration needed to establish a system network connection; it does not fill in missing server details.
If you canceled the prompt, the app may not be able to continue connecting. Return to Home and try again, checking whether the authorization window appears. If you still cannot complete the process, check the VPN configuration and status in system Settings. The wording and location may vary by system version, so refer to what your device displays. Do not delete work- or school-managed network configurations while troubleshooting. If your device is managed, check for applicable restrictions first.
After authorization, return to the app and check whether the switch stays on and whether the system shows an established VPN connection. If the switch turns off immediately, note the app's message, then check authorization and the current server details. Avoid repeatedly tapping the switch. If another VPN connection is already active on the device, identify which one is managing the connection so you do not mistake an old state for the result of this attempt.
A switch that stays on means the connection process has moved to the next stage; it does not prove that the target website is accessible. Server authentication, domain resolution, remote availability, and rule handling may still fail, so you must check actual access next. Do not adjust automatic connection options such as On Demand yet. Stabilize the manual process first to reduce the number of variables.
STEP 04 / VERIFY
Verify with Connectivity Test and actual access
First, run Connectivity Test in the app and check the result for the current server. The result reflects the response to a specific test method and target. It is useful as an initial clue, but does not mean that every website, app, or transport method will work. If there is a response, continue by visiting the target page. If there is no response, consider actual access and error messages as well; do not change every setting based on a single result.
Keep the connection on, switch to your browser, and open a familiar page whose content you can recognize as normal. Reload it if needed, or open a new page to reduce interference from old cached content. Check whether it loads, then whether login, images, and other necessary content work. If you test a page already saved by your browser, you may still see some content even without a network connection. That is not proof of a successful connection.
Next, use a page with a different purpose for comparison. Record whether the current network is Wi-Fi or cellular, the Global Routing mode, the current server, and what happened when you tried to access the page. If the results differ, do not immediately conclude that the client as a whole has failed. Rules may route requests differently, or the target website, DNS, or remote connection conditions may be responsible.
To check whether rules are working as expected, review the connection records or diagnostic information currently available in the app. Focus on the handling policy for the target domain. DIRECT under Config is not necessarily an error; consider the intended purpose of the rules. Check the relevant configuration only if a request that should use PROXY is actually following a different policy. Traffic changes in Data can help you observe activity, but cannot independently prove that a particular page passed through a specified server.
If you temporarily changed the mode to Proxy or Direct, restore the Config mode you originally needed and try the same page again. This process is complete only if you can reproduce the expected result under the intended routing mode. If the results differ, keep your current configuration and test records, then troubleshoot each layer in the next step. Reinstalling repeatedly is not a substitute for identifying the cause.
STEP 05 / TROUBLESHOOT
Troubleshoot common issues in order
Change only one condition at a time, then repeat the same set of tests from Step 4. First note whether the issue is “subscription won't load,” “connection switch won't stay on,” “connected but no pages load,” or “only some pages fail.” Each points to a different stage. Identifying the symptoms is usually more useful than changing servers, configurations, and DNS all at once.
Check the basic network before checking subscription details
Turn off the Shadowrocket connection and check whether the current network can open pages that are normally accessible directly. Public Wi-Fi may require you to sign in first. If the basic network is not available, resolve that issue before continuing. Then return to the app and update your existing subscription. If the update fails, check that the URL is complete, the service is available, and the returned message. If it updates but shows no entries, ask your own service provider to confirm the URL contents and status.
Do not repeatedly add the same URL to try to fix the issue; that only makes the list harder to read. Do not assume an update succeeded just because old entries are still visible; the previous list may have been retained. If you report the issue, describe the error message and the stage where it occurred. Do not include personal parameters from the subscription URL in public screenshots or messages.
Connection failure: Check parameters and system authorization
If the server appears on Home but the connection still fails, open the entry and compare Type, address, port, authentication details, and any additional fields required by your server details. Correct fields that are clearly inconsistent first; do not try every available option at random. Missing details during manual entry, expired imported details, and incomplete system authorization can all cause connection failures, but require different fixes.
If the same server fails only on one type of network, compare Wi-Fi and cellular if possible. Keep all other settings unchanged so that the effects of changing servers are not mistaken for network differences. Ask your own service provider or server administrator to confirm whether the remote server is running, the account is valid, and there are any connection restrictions.
Some pages fail: Check Config, DNS, and test conditions
If Proxy works but Config does not, first confirm which file is enabled in Config, then check the policy for the target request. Keep a copy of the existing configuration before making changes. Change only one relevant setting at a time and record the result. If domain access fails while other requests still get responses, DNS is one area to check, but this symptom alone does not identify the cause. Do not apply an entire set of settings from an unknown source.
If only one website fails, consider the website's own service status or access requirements. When testing the same page, use the same browser and network conditions if possible. For pages that require login, distinguish account issues from network errors. Error messages can provide clues; “page won't open” alone is not enough to determine which layer is responsible.
Prepare redacted details, then check the specific issue
If you still cannot identify the cause, note the device system, current Global Routing mode, protocol type, whether the basic network works, Connectivity Test results, and the exact error text. You can describe the settings you changed, but do not include the full subscription URL, password, or QR code. Visit the connection troubleshooting FAQs to continue based on your symptoms. For App Store access, device recovery, or store region questions, see the acquisition guide. Keep installation issues separate from connection issues.
Keep these three details after setup
Note the selected server, Global Routing mode, and Config file name. If access changes later, check these three details and the current network before deciding whether to update the subscription. Keep your existing settings before adjusting configurations or moving to another device. For more information, see the FAQs.
Return to Step 1 and check again