Getting Started with Shadowrocket
Follow this sequence: import → choose a mode → connect → verify → troubleshoot. This guide uses the iPhone / iPad interface. First establish a connection you can test, then adjust rules and automatic connection settings.
01 Add and import
Open Shadowrocket and go to Home. The import method depends on the details you have: a link that contains multiple servers and can be updated is usually a server subscription; protocol parameters for a single server are suited to manual entry. In either case, you should end up with a selectable server in the SERVER list on Home. Identify the type of information first, then choose the right entry point. This makes issues easier to pinpoint than repeatedly pasting details into different pages.
Add Server: server subscription
Tap the plus sign in the top-right corner of Home to open Add Server. Open Type. If you have a server subscription link, select Subscribe and paste the complete link from your service provider into URL. Add a note that helps you identify it, save, then return to Home and wait for the result. Do not remove question marks, equals signs, or parameters from the link. Avoid copying quotation marks or line breaks included in a chat message.
After a successful retrieval, you should see a subscription group and its servers in Home. Expand the group and check that it contains more than an empty title. A server list means the content was parsed, but does not confirm that a server is currently available. You still need to select a server and test it. If retrieval fails, keep the error message and check that the link is complete and has not expired, and that your current network can reach the subscription address. Do not change routing rules yet.
Add Server: enter details manually
If you have parameters for a single server, open Add Server from the plus sign in Home and select the actual protocol under Type, such as Shadowsocks, VMess, VLESS, or Trojan. Fill in the address, port, password, and other authentication fields using the information from your service provider. If TLS, SNI, or transport settings are shown, enter those as specified in the original details. Required fields differ by protocol. Do not swap parameters just because their names look similar, and do not guess missing values.
After saving, return to Home, find the server you just added, and select it. If you were given a QR code, you can import it with Scan QR Code. Before using it, confirm the code came from your own service provider, then check the protocol and address after scanning. Whichever method you use, this step is complete when an entry matching your details appears under SERVER and can be selected.
After confirming the import, keep one clearly identified server for testing. For now, do not change subscription updates, rules, and On Demand at the same time. The next step is to choose how requests should be handled.
02 Choose a routing mode
Return to Home and open Global Routing. This setting controls how requests are handled; it is not the server list or the connection switch. Even with a server selected, requests may take different paths depending on the mode. To start, remember these three options: Config / Proxy / Direct. After choosing one, return to Home and confirm Global Routing shows your selection.
- Config: Uses the current enabled configuration and rules to decide which policy handles each request. Suitable for everyday use when you have a rule configuration ready.
- Proxy: Sends requests that can typically use a proxy through the selected proxy route. Useful for a brief comparison test, but it does not mean every type of system traffic will necessarily use the proxy.
- Direct: Sends requests directly to their destinations. Use it to check your local network or temporarily connect directly; it cannot verify whether a proxy server is working.
Before using Config, open the Config page in the bottom navigation and confirm that a configuration is selected and enabled. Downloading a configuration to the list does not make it the current configuration; check its selection indicator. If you have a trusted remote configuration address, use Subscribe on that page to retrieve it, then select the relevant configuration. Do not paste unfamiliar rules just to establish a connection, and do not assume a server subscription automatically replaces a complete rule configuration.
If your immediate goal is to check whether the server parameters allow access, select Proxy and continue with the connection and access tests. After confirming that it works, switch back to Config and test the same page. This separates server connection issues from rule selection issues. If Proxy works but a page does not load in Config, focus on the configuration and matching policy rather than immediately deleting and reimporting the server.
When learning about configurations, start with three policy names: PROXY sends a request to the proxy policy, DIRECT connects directly, and REJECT rejects the request. Proxy in Global Routing is related to PROXY in rules, but the former is a global mode and the latter is a policy value for an individual rule. You do not need to edit rule syntax at this point. For matching order, FINAL, and configuration structure, see the Rule Reference.
After choosing a mode, return to Home and check the selected server once more. Next, turn on the connection switch to let the system establish the network channel associated with the VPN configuration.
03 Connect
In the SERVER list on Home, select the server you want to test. Make sure the selection indicator is on the expected entry, then turn on the connection switch at the top of the page. A subscription group name is only an organizational entry; the server used for this connection is a specific server within it. If a group contains several similarly named servers, note which one is selected and keep it unchanged while troubleshooting. This avoids confusing a server change with a mode change.
The first time you connect, iPhone / iPad may show a system prompt asking whether to allow a VPN configuration to be added. Confirm that the request follows the action you just took in Shadowrocket, then allow it and complete any authentication requested by the device. This grants the system permission needed for the app to handle network traffic; it does not import a subscription or fill in a server password. If you deny or cancel the request, the connection may not proceed. Turn on the switch again and complete authorization.
After responding to the system prompt, return to Home and check whether the switch stays on and the connection status changes. The VPN indicator may appear in different places in the status bar on different devices, so do not judge the connection only by whether an icon appears in a particular corner. More importantly, check that the switch stays on, the system VPN status shows connected, and the next access test succeeds.
If the switch turns off immediately after you turn it on, do not keep tapping it rapidly. Check whether you canceled system authorization, another VPN configuration is already active, or device management policies restrict adding a VPN. Check VPN status in system Settings and make sure there is no conflicting connection, then return to Shadowrocket and try once more. On managed devices, follow the limits set by the device administrator; do not remove management configurations you do not recognize.
For this test, do not enable new On Demand conditions yet. On Demand connects automatically based on conditions and is separate from a manual connection. Adding automation too early can cause automatic reconnections or status changes during testing, making it harder to identify the cause. Complete the manual connection and access test first, then learn about On Demand in the Glossary.
Turning on the switch is only the start of verification. It means the system has attempted to establish the network channel; it does not confirm that server authentication, DNS resolution, or access to the destination website has succeeded. Keep the current app state and continue to the next step. Do not end the check just because the VPN status appears.
04 Verify that it works
Return to Home and use Connectivity Test to check server reachability. The test communicates with its target according to its settings. Its result can identify obvious failures, but only covers the path used by that test. A latency value does not mean every website will load. If a test fails, consider how it was run, your local network, and server status; do not change the entire configuration based on one result.
Next, open a browser and visit a page you know is working and that suits your current purpose. Wait for its main content to load, then try opening a regular link on it. Use the same page for comparisons. Visiting one site on one attempt and another site on the next can make a problem with the destination website look like an app issue. If the browser shows cached content, reload the page before checking again.
If you are using Proxy, first confirm that access works through the selected server. Then switch to Config and visit the same page. If the results differ, you have narrowed down the issue: the server may still be working, while the current configuration could be routing the domain through DIRECT, matching REJECT, or using a policy without an available target. Do not change the server and DNS at the same time, or the comparison will no longer be useful.
To check the request path in more detail, open the currently available connection records in Data and look at the domain, time, and policy for the page you just visited. Specific fields may differ between interfaces, so use only the information actually shown. In Config mode, some requests going Direct and others using a proxy may be the expected result of split routing. Do not treat the fact that not all connections use a proxy as a failure.
If a rule or policy is shown in the records, first check whether it uses PROXY, DIRECT, or REJECT, then decide whether it needs adjustment. Rules are usually matched in order: once an earlier rule matches, a later rule will not choose a different policy for that request. For now, record what happened. See the Rule Reference for rule syntax and order; you do not need to change the entire configuration when you are just getting started.
After testing, keep track of three things: which server is selected, which Global Routing mode is in use, and whether the page loaded. If everything matches your expectations, restore the mode you plan to use long term. If you used Proxy temporarily for testing, switch back to Config as needed. If the test did not succeed, continue with the checks below.
05 Common issues
Follow one principle when troubleshooting: change only one condition at a time and retest the same page. First identify whether the failure occurred during import, connection, or website access, then check the relevant area. Resetting everything can erase useful clues and turn one incorrect parameter into several problems. The steps below apply when you have followed the earlier instructions but the result is still unexpected.
Check your local network first
Temporarily turn off the Shadowrocket connection switch and check whether the device can access the internet on its original network. If public Wi-Fi requires you to sign in on a captive portal, complete that step first. If needed, compare Wi-Fi with cellular data, keeping the server and mode unchanged. If the local network itself is unavailable, updating subscriptions or changing rules will usually not help. Restore basic connectivity first.
Import fails or the list is empty
Check that the link is complete, that you did not copy explanatory text from a message, and that you did not enter a server subscription in the remote configuration field on Config. If it used to work but an update now fails, the link may have expired, authentication may have changed, or the server may be returning different content. Ask your service provider to confirm. Do not paste the complete link into an unfamiliar online tool to test it; it may contain authentication parameters.
A server is listed, but the connection fails
Confirm that you selected the actual server, then check the protocol, address, port, authentication details, TLS, and transport settings. When entering details manually, spaces around the password, an incorrect port, or a missing SNI can cause a failure. If the information came from a subscription, update it once using the method provided by your service provider. Do not edit fields you do not understand. Make sure the device date and time are correct, as this can affect some certificate checks.
The test works, but websites do not load
Check Global Routing and DNS separately. Note the current mode, temporarily use Proxy to access the same page, and check the rules and policies in Config if access then works. If the page fails in both modes but Connectivity Test returns a result, the issue may involve domain resolution, the destination website, server forwarding, or transport conditions. Latency alone cannot prove that DNS is the cause. Compare with another known-working page, then see Troubleshooting DNS Resolution Failures.
Record details that can be checked later
If the issue persists, note the failed step, error message, network type, protocol, selected mode, and any differences before and after changing networks. Remove subscription addresses, server passwords, authentication identifiers, and other sensitive information from screenshots or logs before sharing them. When asking your service provider about server status, provide only the details needed for troubleshooting. Do not share the complete subscription content publicly.
Once the manual connection is stable, enable automatic subscription updates, adjust rules, or set up On Demand one step at a time. Retest access after each change and keep a configuration that is known to work. This makes it possible to return to the last verified state if another issue arises, instead of starting over with the import.