This guide is for users who already have server details or a subscription URL and are setting up Shadowrocket on an iPhone or iPad for the first time. Import and select a server in Home, check Global Routing, then turn on the connection switch. When troubleshooting, treat importing, the VPN connection, and rule matching as separate steps: a server appearing in the list does not mean you are connected, and an active VPN connection does not guarantee that a particular site is routed through a proxy.
Add a Server or Import a Subscription
1. I only have server details. How do I add a server manually?
In Home, tap the + in the upper-right corner to open Add Server. Select the Type first, then enter the details you have. The Type determines which fields appear; choosing the wrong protocol can prevent the connection from working as expected, even if the address and port are correct.
- Choose the protocol shown in your server details, such as Shadowsocks or Trojan. Don’t guess the Type based on the port number.
- Enter the hostname or IP address in Address and the port separately in Port. For example, if your details list
node.example.comas the address and443as the port, enter them in their respective fields.443is not the default port for every server. - Fill in the authentication and transport fields required by the selected protocol. If your details specify an SNI value, enter it as provided; don’t change it to an IP address just because Address contains one. After saving, return to Home, confirm the server appears, and tap it to select it.
2. I have a subscription link. Where do I enter it?
A subscription URL retrieves a group of servers; it is not the Address for a single server. In Home, tap + → Add Server, set Type to Subscribe, paste the full address into the URL field, and save. Return to Home, expand the subscription group, and confirm that servers appear.
- The example
https://example.com/sub?token=xxxxshows the format only. When pasting your URL, keep the query parameters after?and check for extra spaces or line breaks at either end. - To refresh an existing subscription, find its group in Home and use that group’s update action. There’s no need to add the same URL again. The group name remaining visible doesn’t mean the refresh succeeded; expand it to check the contents and look for update errors.
- If the group appears but contains no servers, first check that the link is complete and that you copied a subscription URL rather than a login page address. When reporting an error, don’t include the full subscription URL or authentication details.
Test Servers and Choose One
3. Connectivity Test shows a number. Am I connected?
No. Run Connectivity Test in Home. The result in milliseconds is the response time for that test method, not download speed, and it doesn’t mean every site is reachable. Seeing a test result in the list won’t turn on the connection switch or select the server with the lowest latency for you.
4. I have multiple servers. How do I choose one?
Compare response times under the same network and test conditions, then select a server, turn on the connection switch, and check the pages you actually need to access. Change only one variable at a time; otherwise, you won’t know whether a difference came from the server, network, or routing.
Retest based on which servers time out
Only one server times out
- Keep Wi-Fi or cellular data unchanged, then retest that server and another in the same group.
- If the same server still times out, check its Type, Address, Port, and protocol fields. Don’t change the entire subscription group yet.
Several servers time out
- Disconnect first, then check whether your current network can open a site that normally connects directly. If public Wi-Fi requires a sign-in page, complete that sign-in first.
- Switch to another available network and retest the same servers. If the results change with the network, note the difference; don’t edit authentication details in bulk.
First determine whether the timeout affects one server or is related to the current network. Then decide whether to check the server details or the network.
Global Routing and Config Rules
5. Which Global Routing mode should I choose?
In Home, open Global Routing and choose how connections should be handled. If you have a verified configuration file and want traffic routed by rules, choose Config. For troubleshooting, you can briefly switch modes to compare results, then restore your original selection when you’re done.
Config
RecommendedConnection actions are determined by the rules in the current configuration and their order. If no earlier rule matches, check the final rule, FINAL; don’t assume unmatched connections go direct.
Best for: routing traffic by destination with a verified configuration file
Proxy
Routes connections handled by Shadowrocket through a proxy. Use it to compare results with rule matching under Config.
Best for: checking whether rules are causing an issue while keeping the same server
Direct
Routes connections handled by Shadowrocket directly. This changes the routing mode; it does not turn off the VPN connection switch.
Best for: checking how a destination connects directly on the current network
Scene
Switches routing settings based on configured scene conditions. Check the conditions and corresponding settings before using it; Scene is not another name for Config.
Best for: switching routing modes based on scenes already configured for different network conditions
If the same server works with Proxy, check the rules first
If the same destination is reachable on the same network and server with Proxy but fails after switching back to Config, first check whether an earlier rule matches the destination and what action that rule specifies. Don’t start by re-entering the server password or replacing the entire configuration.
6. What’s the difference between the Config page and Config under Global Routing?
The Config tab at the bottom is where you manage configuration files. Home → Global Routing → Config sets the current connection to route traffic by rules. Adding or editing a file won’t automatically switch Global Routing to Config; selecting Config there won’t select the file you just edited for you.
- First check which file is selected in the Config tab at the bottom, then return to Home and confirm Global Routing is set to Config.
- Check the rules in order to see which one might match the destination.
DOMAIN-SUFFIX,example.com,DIRECTroutes connections matching that domain suffix directly. If an earlier rule already matches, this rule won’t run. - If no earlier rule matches, check the action specified by
FINAL. For example,FINAL,PROXYroutes the remaining connections through a proxy. These examples illustrate the syntax; you don’t need to paste them into your existing file.
Connection Switch, VPN Permission, and On Demand
Connection Switch and VPN Troubleshooting
7. Why does the system ask to add a VPN configuration the first time I turn on the switch?
Shadowrocket needs system permission to establish a VPN connection. After confirming that you initiated the action from Home, tap Allow in the system prompt and complete any verification requested by your device. If you tapped Deny, return to Home and try connecting again. To check the VPN entry in system settings, go to Settings → General → VPN & Device Management → VPN. Menu names vary with your system language.
8. The connection switch in Home won’t turn on. What should I check first?
First, make sure you’ve selected the server you want in Home; seeing a server list alone isn’t enough. Then check whether you completed the initial authorization and whether a system prompt or an error appeared. If another VPN connection is active, check which connection the system is using. If it’s safe to disconnect, disconnect it and try again. Don’t remove configurations provided by your workplace or school just to troubleshoot.
9. The switch is on, but why won’t a particular website open?
The switch indicates the VPN connection status; it doesn’t show which rule matched a website. Keep the same server, check whether other pages work, and note the current Global Routing mode. If it’s set to Config, you can briefly switch to Proxy and retry the same destination. If it fails only under Config, check the order of rules for the destination’s domain and the FINAL rule. Restore the original mode after testing.
10. The connection turns back on after I switch it off. Is the switch broken?
First, check Settings → On Demand in Shadowrocket. If automatic connection is enabled, its conditions may trigger another connection attempt. To check whether it’s responsible, note the current setting, temporarily disable On Demand, then turn off the connection in Home and see what happens. Restore the setting afterward if needed. On Demand determines when a connection starts; Global Routing determines how it is routed. They are separate settings.