When setting up Shadowrocket on an iPhone or iPad, start by testing a manual connection from an existing subscription in Home. Then choose Global Routing and enable On Demand if needed. These 10 questions explain the difference between fetching subscriptions, matching rules, and automatic system connections, and help diagnose an outdated list, a connection switch that will not turn on, or a connection that works while a website does not.
Importing and Updating Subscriptions
1. Where do I import an existing subscription URL?
Add it via Home → + → Type → Subscribe. Subscribe takes a URL used to fetch connection entries. It is not a provider's login page or a rule file used in Config. This guide assumes you already have a provider and subscription; it does not provide, sell, or recommend servers or subscriptions.
Choose a Type
Open Home, tap the “+” in the upper-right corner, go to Type, and choose Subscribe. Do not paste the full subscription URL into the server address field for a single connection.
Enter the URL
Paste the complete URL into the URL field. This is only a format example, not a working subscription:
https://example.com/sub?token=xxxx. Check for missing query parameters and make sure you have not included extra quotation marks, spaces, or line breaks when copying the URL.Save and Check
Tap
Doneto save, then return to Home and check that the subscription group appears and contains entries. Select an entry and test the connection. Seeing the group means the source was added; it does not confirm that entries were fetched successfully or can connect.
2. The server-side entries changed. How do I update them?
Go to Home and pull down at the top of the list to refresh, then expand the subscription group to check the results. If the content at the same URL changes, you usually do not need to add the subscription again. If your provider gives you a new URL, update the subscription address. After refreshing, confirm that the selected entry is still listed, especially if the original entry was renamed or removed.
- Subscription refresh failed: The issue is with reading the subscription URL. First check whether your current network can access other websites, then verify the subscription address and that it is still valid. Do not start by changing
FINALor deleting the entire configuration. - Subscription refresh succeeded, but the connection failed: Fetching the list does not mean the device can connect to a server in it. Keep the subscription, select an entry, and follow the connection checks at the end of this guide.
Global Routing and Config
3. Which should I choose: Proxy, Direct, Config, or Scene?
Choose a routing mode in Home → Global Routing. If you already have a usable rule file, use Config for everyday routing. For comparison, temporarily switch to Proxy or Direct. Note your original setting before switching, and restore it when testing is done so a temporary setting does not become your everyday configuration.
Config
RecommendedRoutes requests according to the rules in the active configuration. A request may use DIRECT, PROXY, or another policy specified by the configuration. The connection switch alone does not tell you which route a particular address takes.
Best for: routing traffic by destination after checking the rule file
Proxy
Routes requests handled by the client through a proxy instead of applying rules individually. Keep the network, destination, and selected entry unchanged, and switch from Config to Proxy. This helps determine whether the rules should be your first area to investigate.
Best for: temporarily comparing proxy routing with rule-based routing
Direct
Routes requests handled by the client directly. This is a routing option, not the same as turning off the connection switch in Home. To see what happens when the client is completely disconnected, turn off the connection before testing.
Best for: checking the direct route while the client remains connected
Scene
Applies routing behavior based on the configured scene conditions. Before using it, check which scene should match the current network. Scene is not another fixed rule file.
Best for: switching routes based on network conditions when scenes are configured
4. How are Config and Rule related?
Config in the bottom navigation manages configuration files. Config under Global Routing is the mode that routes traffic using one of those files. Rule refers to the rules in the file that match requests. Importing a subscription adds connection entries; it does not automatically enable a rule file. After making changes, check which file is active in Config, then go to Home and confirm that Config is selected under Global Routing. Opening a file to view it does not enable it.
DOMAIN-SUFFIX,example.com,PROXY: Matchesexample.comand its subdomains, then applies thePROXYpolicy. If another rule also matches the same destination, check the order of both rules.IP-CIDRmatches an IP address range;GEOIPmatches based on the geographic location associated with an IP address. Neither is a domain suffix rule. When troubleshooting, distinguish between checking the request domain and checking the destination IP.FINAL,DIRECTsends traffic directly when none of the preceding rules match. It is a fallback and does not override a rule that has already matched. To troubleshoot a specific destination, check its matching rules first, then checkFINAL. Do not start by changing the default route for the entire configuration.
On Demand and First-Time Authorization
5. Should I enable On Demand?
Leave it off during initial setup. Select an entry in Home, turn on the connection, and confirm that access works. Then go to Settings → On Demand to enable automatic connections and check the network conditions as needed. On Demand determines when the system starts a VPN connection; Global Routing determines how requests are handled after they are routed through the client. Enabling On Demand will not fix an unavailable server or change Direct to Config.
Choose a Connection Mode for Your Use Case
Initial setup or temporary troubleshooting
- Leave On Demand off in Settings → On Demand and control the connection with the switch in Home.
- Stay on the same network while comparing entries or routing modes one at a time, so automatic reconnections do not affect the results.
Everyday use with automatic connections
- After enabling On Demand in Settings → On Demand, check that the conditions for Wi-Fi and cellular networks match your preferences.
- Switch networks once, then check the connection status in Home. If you do not want automatic connections on a particular network, change its conditions and test again.
If the connection comes back after you turn off the switch in Home, first disable On Demand, disconnect once more, and check whether the system is reconnecting based on its conditions.
6. Why does the first connection attempt ask to add a VPN configuration?
This is an iOS or iPadOS system authorization request. Shadowrocket needs a registered VPN configuration to establish a system-managed connection. Confirm that the prompt appeared after you turned on the switch in Home, then approve it as directed by the system. Authorization allows the device to create a connection; it does not mean the remote server is available.
- Previously denied the request? Return to Home and turn on the switch again. If the system prompts you, review the request and allow the VPN configuration to be added.
- Check the system status: In system settings, go to “General → VPN & Device Management → VPN” and look for Shadowrocket's VPN entry. If a managed device prevents VPN configurations from being added, check with your device administrator. Do not remove configurations for other apps.
Connection Types and Troubleshooting
7. Do I need to switch protocols such as Shadowsocks, VMess, or VLESS?
You do not need to change Type just to test speed. A protocol is the communication method agreed on by the client and server; Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard cannot be substituted for one another by switching Type. If you already have a subscription, use an imported entry. Choose a type and fill in its required fields only when adding an entry manually, using the parameters provided by the server.
- Use the port specified by the server. If your connection details say
443, check that the port is set to443. Do not guess the port based on the protocol name, or assume that two entries are interchangeable just because they use the same port. - Transport settings and authentication details can also vary within the same protocol. If a manual entry behaves differently from a subscription entry, check the address, port, and required fields for that type. Change one thing at a time. When reporting an issue, do not include the full subscription URL, password, or key.
8. Home keeps timing out when I pull down. Should I add the subscription again?
Do not add it again yet. Go to Home and check which subscription group failed, then refresh once over Wi-Fi and once over cellular on the same device. If only one network fails, check whether you need to sign in to a Wi-Fi hotspot or whether that network can reach the subscription URL. If both fail, check that the URL is still valid. Old entries may remain visible even when the latest refresh failed.
9. The connection switch turns on, then switches back off. What should I check first?
First check whether there is a pending system VPN authorization request. Then return to Home and make sure you selected a valid entry rather than just expanding a subscription group. If another VPN is in use on the device, check which connection is active in system settings. If it is safe to disconnect, leave only the connection you are testing. Next, run Connectivity Test on the selected entry in Home. If that fails too, keep the entry unchanged, switch networks, and test again before checking the server parameters.
10. It says connected, but why won't one website load?
Keep the same entry, network, and website. First note the result with Config selected, then temporarily switch to Proxy and try again. If the site loads only with Proxy, check the rule matching that domain and FINAL first. If both modes fail, try a known working website for comparison to narrow down whether the issue is specific to the destination or the connection path. A result from Connectivity Test does not guarantee that every website will work. Restore your original routing setting after the comparison.