STEP 01 / ADD SERVER
Add a server or import a Subscribe link
Open Shadowrocket and go to Home. Here you can view your servers, select one, and control the connection. For your first setup, choose the method that matches the details you have: use Subscribe for a link that updates your server list, or add a server manually if you have its address, port, password, and protocol details. Either method is enough; you do not need to import the same details twice.
Have a subscription link? Choose Subscribe
On Home, tap the add button in the upper-right corner to open Add Server. Under Type, choose Subscribe, then paste the full subscription link into URL. If there is a remarks field, you can enter a name that helps you identify it. Subscription links often contain account credentials, so copy the parameters after the question mark in full. Do not include the webpage title, explanatory text, or trailing spaces.
Check the details, save, and wait for the subscription to finish loading. Then return to Home and check the list. Success means that selectable server entries appear—not just that the URL was entered. If you see a subscription group but no servers, check whether it is still loading, whether your current network can reach the subscription URL, and whether the link is valid. Avoid adding the same subscription repeatedly; duplicate groups can make server selection and updates confusing.
A subscription URL should be the client link provided by your service provider, not an account sign-in page, order page, or general information page. If it opens a webpage instead of returning recognizable subscription data, changing Global Routing will not fix the link. Get the correct URL from your service provider, then return to Add Server and update URL.
Have details for a single server? Select the matching protocol
From Home, open Add Server and choose the protocol that matches your details under Type, such as Shadowsocks, VMess, VLESS, Trojan, or WireGuard. Enter the information provided by your service provider. Required fields vary by protocol: a port and password cannot replace a UUID, and a WireGuard key does not belong in another protocol's password field. Do not guess the protocol based on the server name.
For connections that require TLS, check TLS, SNI, and related settings. The transport method, path, and hostname should also match the original details. Keep certificate verification enabled; turning it off is not a routine troubleshooting step. Save your changes, return to Home, select the server you want to use, and confirm that the selection indicator changes. This saves the server details; the next step determines how requests are routed through it.
If your service provider supplies a QR code, use Scan QR Code from the add menu on Home and follow the system prompt to grant camera access. After importing, open the entry and check its protocol and address. A successful scan does not guarantee valid settings or an active connection. For explanations of protocol fields, see Settings Reference and Options Guide.
STEP 02 / GLOBAL ROUTING
Choose a Global Routing mode
After importing, stay on Home and open Global Routing. This setting determines how the client routes requests; it is separate from choosing a server. Changing servers does not automatically switch Direct to Proxy, and importing a subscription does not mean suitable rules are enabled. Before your first connection, check both the selected server and the routing mode.
Config: Route requests according to rules
Config is suited to everyday use with rule-based routing. Requests follow the rules in the active configuration and may use PROXY, DIRECT, or REJECT. Before selecting this mode, open Config in the bottom navigation and check which configuration is active. If there are several files, do not rely on their names alone; verify the selected file and its rules.
Subscriptions and configuration files serve different purposes: Subscribe mainly provides server details, while Config contains rules and related settings. Seeing servers in the list does not mean Config has rules that meet your needs. If your service provider also supplies configuration instructions, check what they are for before importing anything. Do not replace an existing file with a remote configuration you do not understand. Keep a copy of your current configuration so you can restore it.
Proxy: Verify the selected server route first
Proxy routes requests handled by the client through the proxy mode. It can reduce the variables introduced by rule-based routing during an initial test. Select Proxy, return to Home to confirm the selected server, then continue to the connection step. Proxy does not change server settings or fix an expired account or incorrect password.
If real-world access works in Proxy but fails for the same request in Config, the two requests may have followed different policies. Check the configuration and which rules matched instead of immediately deleting the server. After testing, switch back to Config if it suits your everyday needs and test again. One successful request does not prove that every rule or destination is configured correctly.
Direct: Compare against your regular network path
Direct routes requests directly rather than through the selected remote proxy server. Use it to compare with the proxy route, not to confirm that the server connection is working. If a server is selected on Home but Global Routing is set to Direct, turning on the connection switch does not show that the proxy route is active.
No single mode is right for every situation. For initial troubleshooting, use Proxy to test an existing server, then switch to Config to check how rules behave; use Direct to observe your regular network path. For advanced settings such as rule order, FINAL, and DNS, see the Options Guide. First, complete a connection test you can repeat.
STEP 03 / VPN
Turn on the connection and approve the VPN configuration
Return to Home and check the selected server and Global Routing once more. Then turn on the connection switch at the top. The first time you connect, the system may ask whether Shadowrocket can add a VPN configuration. This permission lets the client handle network traffic through the system. Confirm the app name in the prompt, follow the system instructions, and complete any required passcode or biometric authentication.
If you previously denied permission, the connection switch may not stay on. You do not need to import the subscription again; try connecting once more and respond to the system prompt. If device management or system restrictions prevent adding a VPN configuration, check the device's management requirements rather than repeatedly switching servers. System approval only grants the client the required permission; it does not mean the remote server is available.
After approving the prompt, return to Shadowrocket and check whether the switch stays on and the connection status remains stable. The VPN indicator may appear in different places depending on the device and system layout, so do not rely on a single icon as your only check. Next, use Connectivity Test and try real-world access to confirm the connection can carry requests.
If another system VPN connection is already in use, check which configuration is active so you do not mistake its status for Shadowrocket's. Also check On Demand during initial testing: automatic connection behavior can make the manual switch harder to interpret. Identify the active connection first, then decide whether to change the On Demand conditions.
When you finish testing, return to Home, turn off the connection switch, and confirm that the status changes. Test again after switching between Wi-Fi and cellular, as either network may have different access to the same server. An active connection, a test result, and a successfully loaded page are three separate observations; record each one.
STEP 04 / CONNECTIVITY TEST
Check connection status and real-world access
Find Connectivity Test on Home and run it. Check the result shown for the server. The test method may depend on related settings under Settings, so interpret the result in that context. A time value usually means the test received a response; a timeout means that this test did not finish within the allotted time, not that the server is permanently unavailable.
Connectivity Test does not exactly replicate requests from real apps. A successful probe does not confirm that TLS, authentication, DNS, and access to the target site are all working. Conversely, a server that does not respond to one type of probe may still handle other requests. Do not treat a latency figure as proof of success or a guarantee of real-world speed or reliability.
Compare results using the same destination
Keep Shadowrocket connected, then use a browser to visit a page where you can tell whether it has loaded correctly. Check that the content and essential resources appear, rather than relying on a cached page title. Open a new page or refresh the content to reduce the chance of a misleading cache result. Keep the network, server, and routing mode unchanged during the test; do not change several things at once after a failure.
With Config selected, check request records or logs to see which rule matched the destination and which policy was used. A page may load through DIRECT, so successful access alone does not prove it went through PROXY. To test the proxy route, temporarily switch to Proxy and repeat the same test, then restore the previous mode and compare the results. The location of request records depends on the version of the app.
If you need to check your exit IP, use a test destination you trust and review the rule records as well. The result for one destination only describes the route used for that request; it does not mean every request from your device takes the same path. In Config, different domains, addresses, and app requests may match different rules. That is expected with rule-based routing.
You have completed the initial check when the correct server is saved and selected, the current Global Routing mode is clear, the system connection stays on, and the result for a real destination matches the selected policy. Note the network type, server remark, and routing mode so you can repeat the same test if a problem occurs instead of relying on memory.
STEP 05 / CHECKLIST
Troubleshoot common issues by failure stage
First identify whether the problem occurs during import, connection, or access. If import fails, server details have not been retrieved; switching Proxy repeatedly will not help. If the switch turns on but pages fail to load, reinstalling the app should not be your first step. Keep existing entries and configurations, change one setting at a time, and retest the same destination to see what made a difference.
No servers appear after saving a subscription
Return to the subscription settings and check that URL is complete. Look for line breaks, truncated parameters, or an expired link. Confirm that your current network can retrieve the subscription data. If the URL itself is unreachable, resolve the access issue or get a valid link first. Your service provider manages subscription status separately from the app purchase; buying the app again will not restore an expired subscription.
If entries disappeared after an update, first check whether the subscription returned different content or whether a filter is active; do not delete entries in bulk. A subscription update may overwrite the server details it manages, so note the original values before editing them manually. If you are still unsure, ask your service provider to confirm that the subscription is valid. Hide identity parameters in the link before sharing it.
Connectivity Test times out or the server does not work
First confirm that you selected the intended server, then check Type, address, port, and authentication details. If TLS is required, verify SNI and related transport settings; do not mix up the domain, address, and host fields. Check that the date and time on your iPhone or iPad are correct, as an incorrect clock can affect certificate verification. Do not hide incorrect settings by turning off security checks.
Next, select another known-working server from your existing entries and compare the results without changing the routing mode or destination. If possible, you can also switch networks and test again. If only one network fails, first consider whether that network can reach the server. If all networks fail, check your account status and server details. Always assess test results alongside real-world page access.
The connection switch turns off immediately
First check that system VPN permission was granted, whether another system VPN is switching connections, and whether device management imposes restrictions. Then confirm that the current configuration can be read by the client. If you recently edited Config, restore the last known working configuration and test the switch again. A connection that will not stay on is a different issue from a slow server response; troubleshoot them separately.
If On Demand is enabled, check whether its conditions automatically connect or disconnect on the current network. For an initial test, understand these conditions first; if needed, temporarily disable automatic triggers and note the change. After manual testing, restore them if appropriate. Repeatedly tapping the switch makes status changes harder to track, so wait for each action to finish.
Some pages load, but others fail
First compare the results for the same destination in Proxy and Config. If only Config fails, check rule order, the matched policy, and whether the destination is being handled by REJECT. If both modes fail, check server details, DNS, and the destination itself. Do not replace the entire ruleset at the outset; identify the specific request first to avoid disrupting parts that already work.
DNS affects how domain names are resolved, while routing rules determine how requests are handled. They are related but separate settings. If a domain fails to resolve, first check the active configuration and the DNS settings currently in effect under Settings. Do not paste together settings from multiple sources. For detailed parameters and log-reading guidance, see the Options Guide; this page focuses on troubleshooting a first connection.
After troubleshooting, return to the connection verification steps and repeat the same checks. Once the connection works, choose Config for everyday use if needed and adjust settings one at a time. Keeping a restore point before each change is easier to manage than changing the server, rules, and DNS all at once.