User Guide · Getting Started
Shadowrocket
Import a Subscription and Connect
Save an existing server to Home, choose Global Routing, then connect and verify an actual request. This page walks through a repeatable connection check without requiring you to understand an entire configuration file first.
You can skip steps you have already completed. If something goes wrong, return to the last step you confirmed was working and continue checking from there. Entry locations may vary slightly by system version; identify features by their current English names in the interface.
STEP 01 · Home / Add Server / Subscribe
Add a server or import an existing subscription
After opening Shadowrocket, stay on Home. Here you can view saved servers, choose the current connection target, and turn the connection on or off. Do not connect yet: if the list is empty, import a server first. If entries are already listed, confirm that the one you choose belongs to a valid subscription of your own rather than selecting by name alone. A subscription is an address used to retrieve a set of server details; an individual server is a specific connection entry, and the two are set up differently.
Have a subscription link? Use Subscribe
Tap the add button in the upper-right corner of Home, open Add Server, then open Type and select Subscribe. Paste the complete subscription link into URL, add an optional note to help identify it, and tap the save button in the upper-right corner. Check that the pasted link has no leading or trailing spaces, line breaks, or chat text. Copy the entire link, not just the domain, and do not remove the parameters after the question mark. These parameters are often part of the subscription credentials; missing any of them may prevent the content from loading.
After saving, return to Home and wait for the subscription content to load. A subscription group and its server entries should appear. Select one entry and confirm that the selection indicator is on the server you intend to use. If the subscription name appears but there are no servers inside it, the import is not complete; check the retrieval result first. To refresh, use the update action for that subscription entry. The exact location may be in the entry's action menu; check whether the list changes after updating.
Do not repeatedly create the same subscription just to refresh it. Duplicate groups make later selection and troubleshooting confusing and may lead you to use an outdated entry. An update retrieves the data provided by your service provider, and new content may overwrite entries you manually changed within a subscription. If you need to keep separate edits, confirm how they are saved before updating.
Have individual server details? Set the Type
If you have individual server parameters, start from Add Server, but select the protocol provided by your service provider under Type, not Subscribe. Enter the server address, port, authentication details, and any other fields required by that protocol. For example, if UUID, TLS, or Server Name is required, check each value against the original details. Do not mix fields from different protocols or infer the protocol from the appearance of an address.
After saving, return to Home and select the new entry. If you have an existing QR code, you can also import it with Scan QR Code, but check the detected Type and address afterward. Subscription URLs, QR codes, and authentication fields may contain access credentials, so do not share screenshots or forward them. Once this step is complete, you should know exactly which server you intend to connect to before choosing a route.
STEP 02 · Global Routing / Config
Choose a Global Routing mode
The server determines which destination the proxy connection uses; Global Routing determines how requests are handled. Open Global Routing from Home and identify the three modes: Config, Proxy, and Direct. This tutorial uses these modes for basic checks. If the interface shows other options, keep to the task at hand; there is no need to configure every feature at once.
Config: follow the current rules
If you have a suitable configuration file, choose Config for everyday use. Then open Config and confirm that the intended file is actually enabled, not merely present in the list. Importing a subscription and setting up Config are different tasks: a subscription mainly updates server details, while Config controls behavior such as rules and DNS. Successfully importing a subscription does not mean you have obtained routing rules suited to your needs.
Rules are generally matched in order, and the first matching rule determines the policy for a request. For example, the snippet below sends the example domain through PROXY and uses FINAL as a fallback for everything else. It only illustrates rule matching and is not a complete configuration to replace your existing file; PROXY must also refer to a valid policy in the actual configuration.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
Proxy: check the selected proxy route
If you do not have a suitable Config yet, or are checking whether a problem is caused by a rule, you can temporarily select Proxy to test requests handled through the selected server. It does not automatically fix problems or fill in incorrect authentication parameters. System traffic and requests restricted by the system may still be exceptions, so do not treat this mode as an absolute guarantee for every packet on the device.
Direct: compare against the local network
Direct sends requests over a direct route and can help you check whether the current Wi-Fi or cellular network is working. It does not test the proxy server. If a page loads with Direct but not Proxy, continue by checking the proxy route. If neither works, consider the destination, local network, or DNS instead of immediately rebuilding the entire configuration.
Make a note of the mode you selected. During initial troubleshooting, do not change rules, switch servers, and change modes all at once; otherwise, you will not know which change made a difference. For more on rule structure and settings, read the settings reference. For now, confirm the server and routing mode, then connect.
STEP 03 · Home / VPN
Turn on the switch and check the system connection
Return to Home and check the server selection indicator and Global Routing once more. When everything is correct, turn on the connection switch at the top. The first time you connect, your iPhone or iPad will show a system prompt to add a VPN configuration. Read the prompt, confirm that Shadowrocket initiated the action, allow it, and complete device authentication as requested. This authorization is required to establish the system network tunnel; it is not part of importing a subscription.
If you previously canceled authorization, return to the app and start the connection again. Do not try to fix it by importing the subscription again. Even if Home lists multiple servers, that does not mean a connection has been established while system authorization is incomplete. After completing the prompt, return to Shadowrocket and check whether the switch stays on and the connection status updates. If needed, check the VPN status in system settings; the two should correspond.
If the switch turns off immediately after you turn it on, first check whether the app or system provides an error message. See whether another VPN connection is using the system tunnel. If needed, disable the other connection before trying again in Shadowrocket. Do not delete the system configuration without noting its current state; you may need to authorize the connection again, and deletion adds another variable to the troubleshooting process.
If the connection keeps coming back after you turn it off manually, check whether On Demand is enabled or another automatic system connection condition is in effect. While getting started, note these settings and temporarily disable the relevant automatic connection conditions before testing a manual connection. This helps distinguish an app-initiated connection from one the system re-establishes under certain conditions, so you do not mistake it for an unresponsive switch.
A switch that stays on only indicates that the connection process is active; it does not guarantee that the selected server, domain resolution, or rules are behaving as expected. Do not immediately switch between several servers. First test with the same server and record the connection status and actual access results separately.
STEP 04 · Connectivity Test
Check the server, access results, and rules separately
After connecting, run Connectivity Test and check the result for the selected server. The test may be in a tools or actions menu on Home. If the interface lets you choose a test method, use the same one when comparing servers. A successful result means the expected response was received under that test condition; it does not verify every website, protocol, or app.
If the result only reflects a network probe response, it cannot confirm that authentication and full proxy access are working. Different test methods may check different parts of the route. Next, open a browser and visit a page you know is available and that matches the current routing mode. Refresh the page or make a new request so that previously loaded content or cached data is not mistaken for the result of this connection.
When verifying Config, distinguish between a page that loads and a request that follows the intended rule. A page may load because it matched DIRECT rather than PROXY. Open the request records or Log provided by the app, find the domain you just visited, and check the matching rule and final policy. If the record does not show the request, first confirm the time, domain, and current connection; do not infer the route from page load speed alone.
When verifying Proxy, use the same destination and server to compare actual access before and after connecting. Use Direct to check the basic network. Each mode serves a different testing purpose, so the results do not need to match across all modes. In particular, do not rely solely on the VPN indicator in the status bar: it shows the tunnel status, not the final policy used for every request.
Finally, check the setup for everyday use. If you temporarily switched to Proxy to troubleshoot, restore the Config you intend to use, make a new request to the destination, and check the records again. You can note the current configuration file name, server name, Global Routing selection, and test results, but do not include authentication details in a public record. The setup is complete only when it behaves as expected after you restore the mode you plan to use.
STEP 05 · Locate the failure stage
Common failure points and what to check next
Identify where the failure occurs before deciding what to change. Record four results: whether the subscription updates, whether the server test succeeds, whether the connection switch stays on, and whether the destination request succeeds. Change one thing at a time and retest the same destination. Once the issue is resolved, undo temporary diagnostic changes. This preserves useful information better than repeatedly uninstalling and reinstalling the app.
Subscription is empty or fails to update
First, return to the subscription settings and check that the URL is complete, Type is set to Subscribe, and the link has not expired. If the response is a login page, text message, or empty content, the app cannot use it as a server list. Ask your service provider to confirm the subscription address and response format rather than guessing the parameters. Subscription retrieval happens before connecting, so an update failure does not necessarily mean that every server is unavailable.
If the server list is present but an update fails, keep the existing group, check whether its current entries still work, and then determine whether the issue is subscription retrieval or server connectivity. Do not share the full subscription URL when asking for help. Describing the error, the stage where it occurred, and the checks you have already made is usually more helpful. Treat a subscription containing access credentials as sensitive information.
Server test fails or there is no access after connecting
Check the address, port, protocol, and authentication fields one by one. For entries with TLS enabled, check that the relevant name matches the server requirements. Do not change ports at random. If the details came from a subscription, first check that the subscription updated correctly, then ask your service provider to confirm the server status. Switching between Wi-Fi and cellular can provide a comparison, but run the test again after each switch rather than relying on an earlier result.
If all destinations fail with Direct as well, check the local network first, for example whether you need to sign in to Wi-Fi or whether the network is connected. If the switch will not stay on, check system VPN authorization and connection conflicts. If the switch is on but requests fail, check the server, resolution, and policy. Separating these stages helps avoid wasting time changing rules when the issue is system authorization.
Only some pages or apps fail
Compare the results for the same destination with Config and temporarily with Proxy. If Proxy works but Config does not, focus on the rule that matched, its policy target, and rule order. If a domain fails while other requests work, check DNS records and configuration. Do not replace every DNS parameter based on a single symptom, and do not overwrite the entire Config without a backup.
For more advanced operations involving DNS, On Demand, Log, or restoring a configuration, follow the relevant steps in the settings reference. See the frequently asked questions for more troubleshooting organized by symptoms. Before sharing diagnostic details, hide sensitive fields such as subscription URLs, passwords, and UUIDs. Keep the interface terms, error text, and order of actions.
Once everything works, keep the server selection and Config that you know are usable, and change only one setting at a time. To update a subscription, update its existing group; before changing rules, save the current configuration. After each change, follow the same check sequence: connection status → Connectivity Test → actual request → matched policy.