Shadowrocket Setup Guide
Start with your existing subscription or server details, then add them, choose a routing mode, connect, and test. Get one connection working before adjusting rules or On Demand settings.
Workflow: First make sure your connection details are complete, then choose how to add them. After turning on the connection switch, test actual requests as well. Subscriptions and configuration files are different types of content; don't choose an import option based on the file name alone.
Add Server: Add a Server or Import a Subscription
Choose either manual entry or subscription import. To confirm the import worked, look for a selectable server under SERVER in Home—not just a saved link.
Add a Server Manually: Enter Fields for the Selected Type
Open Home in Shadowrocket, find Add Server in the SERVER section, and tap it. Tap Type first and select the protocol specified in your server details, then enter Host and Port. Enter the server address provided by your provider in Host; don't paste the full subscription link there. Enter the port in Port without extra text. The fields shown after you select a protocol depend on the protocol and server configuration, which also determine whether each field is required.
For example, if you select Shadowsocks, enter the Password and Method from your server details. Don't choose an encryption method based only on a similar name. For VMess, VLESS, Trojan, or Hysteria2, also check the relevant identity, TLS, and transport settings. Don't reuse parameters from one protocol for another. If your provider's details are missing a required field, ask for the complete details rather than trying random values. You can add a label to help identify the entry, but it can't replace the server address or authentication details.
When you've checked the details, save and return to Home. Confirm that the new entry appears under SERVER with the expected name, then select it. This only confirms that the details have been entered; it doesn't show that the server is reachable. If you have a server QR code, scan it from Add Server using Scan QR Code. After importing, open the entry and check details such as Type, Host, and Port. A successful scan doesn't mean the connection works.
Subscribe: Import Your Existing Subscription
If you have a subscription link, select Subscribe in Add Server, enter the complete link in the appropriate field, add a label to identify it, and save. Preserve the original query parameters when copying; remove chat text, line breaks, and quotation marks around the link. Subscription links may contain access credentials, so don't post them in public comments or screenshots. If you need help, describe the error and hide any sensitive parts of the link.
Return to Home and wait for the subscription content to load. If needed, update the subscription entry. When successful, you should see server entries generated from the subscription. If you see the subscription name but no servers, first check for retrieval errors, then confirm the link returns subscription content Shadowrocket can read—not a login page or regular webpage. Avoid repeatedly creating subscriptions with the same name to fix a single failure; doing so makes it easier to select the wrong entry later.
Updating a subscription syncs remote server details. It is not the same as importing a rule configuration, and local changes to the subscription entry may not be preserved. Select a server with complete details to continue. For help with failed updates, changed content, or duplicate entries, see FAQ. For configuration file structure, see Configuration Reference. You don't need to change rules in this step.
Global Routing: Config, Proxy, and Direct
The server entry determines where to connect; Global Routing determines how requests are handled. Check these two selections separately.
After adding a server, return to Home and tap Global Routing to see the current mode. The three common options are Config, Proxy, and Direct. Check which one is selected before making a change. Don't switch between multiple modes after a connection failure, or it will be difficult to tell which change affected the result.
Config: Match Requests Against the Active Configuration
With Config selected, requests are handled according to the rules in the active configuration. Open Config to confirm which file is in use, then check its Rule section. A configuration file appearing in the list doesn't mean it's active; editing a different file won't change the rules used by the current connection. If you're new to Shadowrocket, first make sure the active file is the one you expect. You don't need to change General, Rule, and every other section at once.
Rules are usually checked from top to bottom. When a rule matches, its specified policy is applied. For example, DOMAIN-SUFFIX,example.com,PROXY routes the specified domain suffix through PROXY, while IP-CIDR,192.168.0.0/16,DIRECT matches the specified IP range. A final FINAL,PROXY rule sets how requests not matched earlier are handled. These are syntax examples; don't replace your existing active rules with them wholesale.
PROXY, DIRECT, and REJECT are policy keywords; don't replace them based on assumptions about what they mean. When checking rules, also confirm that the referenced policy or policy group exists and that its selected destination is correct. For more on rule types, DNS resolution, and matching conditions, see Rules and Rule Order. For this tutorial, first identify the active file and its actual policies.
Proxy and Direct: Compare Request Paths
Select Proxy to check whether the selected proxy route works, without bringing complex rules into the test. Select Direct to check a direct connection; this doesn't prove that the selected proxy server works. If Proxy works but a destination fails under Config, check the rule and policy matching that destination before re-entering all your server details.
After choosing a mode, return to Home and check the Global Routing value again. Confirm which server is selected under SERVER. When you're done comparing, switch back to the mode you intend to use. If you plan to use rules, this is usually Config, with the configuration you've just verified. Next, turn on the connection switch without editing the configuration file at the same time.
Home: Connect and Allow the VPN Configuration
Confirm the server and Global Routing first, then turn on the switch at the top. System authorization and server authentication are separate.
Return to Home and confirm that SERVER has the server you intend to test selected, not an older entry with the same name. Check that Global Routing matches your selection from the previous step. Then turn on the connection switch at the top of the screen. Before connecting, the status may show Not Connected. The change in status after switching on indicates whether the system connection was established; it doesn't by itself show whether a particular website is accessible.
The first time you connect, the system will ask permission to add a VPN configuration for Shadowrocket. Check that the app name in the prompt matches the app you're using, then allow it and complete any required device authentication. This creates a VPN configuration for the system network extension; it doesn't ask you to enter your server Password again. Don't enter your server password in an unrelated system authentication prompt, and you don't need to find and import another configuration file for this step.
After confirming the system prompt, return to Shadowrocket and check whether the connection switch stays on and the status changes from Not Connected to connected. If you canceled the system prompt, the app may not be able to establish a connection. Try connecting again and follow the prompt to authorize it. You may also need to repeat this step if you previously deleted the VPN configuration from system settings.
If the switch turns off right away, note whether you saw a permission prompt or error message. In iPhone or iPad system settings, search for VPN and check whether the configuration is present and whether another connection is currently handling network traffic. Don't delete all network settings without first noting what happened. Check permissions, the current connection, and in-app settings first; that usually makes the issue easier to find. Devices with management restrictions must also follow their management policies.
Once the switch stays on, let the app update its status before testing access. A VPN indicator in the system only means the relevant system connection is active; it doesn't confirm that a subscription is valid, server authentication succeeded, remote destinations are reachable, or every routing rule works. Don't turn on On Demand or switch between multiple servers yet. Keeping the current conditions unchanged lets you match the test results to this connection in the next step.
To pause the connection, return to Home and turn off the switch at the top. Consider On Demand only after you've tested connecting and disconnecting manually. For details on the first authorization prompt and what to do if the configuration was deleted, see About the VPN Configuration Prompt.
Connectivity Test: From Testing to Actual Access
Check three separate things: “the test responds,” “the system is connected,” and “the destination is accessible.” One doesn't prove the others.
Test the Current Server, Then Open a Destination
In Home, find Connectivity Test, run it, and wait for the result. Start by checking the result for the selected server; there's no need to compare the entire list at once. Results depend on factors such as Test Method in Settings, the current network, and the test destination. A response only confirms a result under those test conditions; it doesn't prove that all protocol settings, destinations, and rules are correct.
Next, open a browser and visit a destination you're authorized to use that normally works. Use a specific URL if possible, wait for the page to load, and check whether you can use its main features. Don't rely on a cached homepage or stale content that hasn't refreshed in an app. Reload once if needed, and note whether the problem occurs during DNS resolution, connection, loading, or sign-in. A website sign-in failure isn't necessarily a proxy connection issue; distinguish it from a failed network request.
Use Data to Check the Applied Policies
If a page loads but you want to confirm that it used the expected route, check the relevant request records in Data. Use the information available in your current version to verify the destination domain, matching rule, and applied policy. Under Config, some requests matching DIRECT are simply following the rules; that doesn't mean the connection is disabled. Likewise, turning on the connection switch doesn't mean every request should use PROXY.
If only one destination fails, keep the server unchanged and compare the results under Proxy and Config. If the former works and the latter doesn't, check the active configuration, rule order, and policy group destination. If both fail, check the server details and remote status. When using Direct for comparison, remember that it changes the request path; its result doesn't count as a successful test of the proxy server.
A useful test records conditions you can reproduce: the network, selected server, Global Routing value, destination address, and error. Switching between Wi-Fi and cellular can help isolate network-specific issues, but retest after switching rather than comparing results from different networks. The basic connection check is complete only when the destination is accessible and the applied policy matches your expectations.
Settings: Common Issues and Next Steps
First identify which step failed, then change the relevant setting. Change one thing at a time and keep the original settings so you can restore them.
Import Failed: Check the Link and Its Contents
If the failure occurs while saving or updating in Subscribe, first confirm that the device can access the internet, then check that the link is complete and its credentials are still valid. An error retrieving a subscription doesn't mean that every server in the list is unavailable. Confirm the link's intended use and content format with your provider; don't use a rule configuration URL as a server subscription. If the link needs updating, edit the existing subscription first, then check how its entries changed.
Test Timed Out: Check the Parameters and Test Method
If the server is imported but Connectivity Test doesn't respond, open Settings and check Test Method to understand how the current test works. Then check Type, Host, Port, authentication details, and the relevant TLS and transport settings. Different test methods can produce different results; don't keep changing unknown fields just to get a response. Make sure the device date and time zone are correct. System time is especially important for certificate validation, so don't disable or weaken validation as a shortcut.
If the same server fails on one network but works on another, record both results and check whether the current network has additional restrictions. If all parameters match the original details but the connection still fails, ask your provider to confirm the server status and that your details are still valid. Before sharing the issue with anyone, hide your Password, identity credentials, subscription link, and any other information that could grant access to the service.
Connected but Some Requests Fail: Check Rules and Records
If the switch stays on but only some pages fail, check the related requests in Data, then review Global Routing and the active Config. Confirm whether the request matched the expected PROXY, DIRECT, or REJECT policy, and whether the policy group selected a working destination. If DNS resolution is involved, note the specific domain and error. Don't change DNS, the rule file, and the server all at once. For more on DNS and rule fields, see the Configuration Reference. First pinpoint the issue, then read the relevant section.
Diagnostics and On Demand: Use After the Basics Work
Diagnostics in Settings can provide more information for troubleshooting. Diagnostic records are a tool, not a substitute for valid server details. Check for private addresses or credentials before sharing them. If an issue keeps recurring, record the steps, error message, and network conditions; that's more useful than simply saying “it doesn't work.” For a full timeout troubleshooting sequence, see the Connection Failure Checklist.
Set up On Demand only after you've confirmed that a manual connection works. Before enabling it, understand its triggers and decide when you want a connection to start automatically. It won't fix an invalid subscription or incorrect server details. If the connection comes back on after you turn it off, check On Demand and its related triggers. For background connection and battery trade-offs, see When to Use On Demand. You don't need to configure everything when you're just getting started.
When you're done, keep a combination you've verified works: the server, Global Routing mode, and active configuration. Before making further changes, back up your settings and change one field at a time. Repeat the checks: connect, test actual access, and review the records. This gives you a known working setup to return to if something goes wrong, without having to import everything again.
