01 · Add Server / Subscribe
Open Shadowrocket and go to Home. Here you can view your saved servers, select one, and control the connection. First, identify what information you have: use Subscribe to import a link that updates a server list; enter the protocol-specific fields for a single server with an address, port, and authentication details. Choose one method—there's no need to add the same details twice.
Have a Subscription Link? Use Subscribe
Copy the complete subscription link from your provider, return to Home, and tap the plus button to open Add Server. Select Subscribe under Type, paste the link into URL, and add a note to identify it. Before saving, check that the link hasn't been cut off at either end. Don't include explanatory text, line breaks, or spaces from the message it came in. Subscription links may contain credentials; keep them only on devices you trust and don't share them publicly.
After saving, return to Home and wait for the subscription to update. If the list hasn't expanded or no servers appear, use the update action for that subscription and check again. On success, you should see server entries in the subscription group, not just the subscription URL. Updating a subscription syncs the list; it doesn't connect you or confirm that every listed server works. Select a server, then run Connectivity Test later in this guide.
If the subscription saves but no entries appear, don't keep creating new subscriptions. First check that you copied the client subscription URL, not an account management page address, then confirm your current network can access it. An expired link, changed authentication, or an unsupported subscription format can cause the update to fail. Keep the original entry, follow the checks at the end of this guide, and ask your provider to confirm the URL is still valid.
Have Details for One Server? Enter Its Protocol Settings
In Home, tap the plus button to open Add Server. Choose the Type that matches your details, such as Shadowsocks, VMess, or Trojan, then enter Address, Port, and the required authentication fields. Each protocol uses different fields: a password can't replace a UUID, and transport settings can't be inferred from the server name. If your details specify TLS, a transport method, or a server name, check each value against the source rather than leaving uncertain fields blank or substituting values.
After saving, return to Home, find the new entry, and select it. The server name is just a label; the protocol, address, port, and authentication settings determine whether it connects. Seeing an entry only confirms that its details were saved locally. Choose Global Routing before connecting. There's no need to add lots of rules or change multiple Settings at once.
02 · Three Global Routing Modes
After selecting a server, open Global Routing in Home. This setting determines how requests are handled overall; it's separate from choosing a server. Even with the right server selected, the wrong routing mode can leave the connection active while requests to your destination don't go through that server. Understand the three options before choosing one for your test.
| Mode | What It Does | What to Check |
|---|---|---|
| Config | Selects a policy based on the rules in the current configuration file. | Is the configuration enabled, and which rule matches the destination? |
| Proxy | Routes proxyable connections through the selected server, simplifying an initial test. | Is the selected server working, and can the request complete? |
| Direct | Connects directly without using the selected server as a proxy. | Was Direct selected intentionally, and can the current network reach the destination directly? |
If this is your first time using Shadowrocket and you don't have a configuration file yet, select Proxy to test the connection and access in the next step. This separates checking whether the server connects from checking whether the rules are correct; it doesn't mean you should always use the same mode. Proxy also doesn't guarantee that every app or type of system traffic will go through the proxy. Verify each request in practice.
If you already have your own configuration file, open Config and confirm that the intended file is active. Then return to Home and select Config. Importing a file into the Config list doesn't activate it, and selecting Config as the routing mode doesn't prove that every rule matches your needs. Importing a subscription usually updates the server list; that's different from importing a full rules configuration.
Direct is useful for checking whether the current network can reach the same destination directly. It won't fix a failed connection or replace server authentication. To learn more about PROXY, DIRECT, REJECT, and rule matching order, read the Rules and Configuration Reference after completing this guide. For your first connection, keep the number of variables to a minimum.
03 · Home Switch and VPN Authorization
Return to Home and confirm the selected server and Global Routing once more. When you're ready, turn on the connection switch. The first time you connect, iOS may ask to let Shadowrocket add a VPN configuration. Check the app name, make sure you initiated the action, then tap Allow and complete any required passcode or biometric verification. This prompt creates the system configuration needed for the network extension; it isn't a subscription import screen.
After system verification, return to Shadowrocket and check the switch and connection status. If the switch is still off, turn it on again. System authorization and a successful connection to a remote server are separate: authorization allows the app to create a local connection tunnel, while the remote connection also depends on the server address, authentication settings, and network conditions. A VPN status indicator only confirms the local tunnel state; it doesn't prove that requests to a remote server are succeeding.
If you canceled the prompt, turning the connection switch on again will usually bring it back. If another VPN connection is active on your device, disconnect it before testing Shadowrocket to avoid mistaking connection switching for a server problem. Organization-managed devices may restrict VPN configurations. If you see a management restriction, check the device's management requirements rather than repeatedly deleting system settings.
During your first test, leave On Demand off. Using the manual switch makes it easier to check each step. On Demand triggers connections based on conditions; it won't fix an incorrect password, a bad subscription URL, or the wrong routing mode. Set it up later if you need it, once the manual connection is stable. Keep the connection on and use the same destination in the next step to verify that it works.
04 · Connectivity Test and Access Checks
Return to Home and run Connectivity Test for the selected server. Results depend on the test method: a response time means the test received a response at that moment; a timeout means it didn't finish within the allowed time. This test isn't an overall measure of website performance, and its result isn't the same as everyday page-loading speed. Don't keep switching servers based on a single test.
Check Test Results Alongside Real Requests
Keep the same server and Global Routing mode selected. Open a browser and visit a familiar page that's currently available. Check that it loads, then open another link on the page to make sure you're not just seeing cached content. If only one app has a problem, try a similar destination in a browser first; an app-specific login, cache, or service issue doesn't necessarily mean the whole connection is down.
Back in Shadowrocket, use traffic data in Data and any available connection records as supporting evidence. A change in traffic shows that network activity occurred, but traffic alone can't tell you which rule matched a destination. If request logging is available, find a request that matches the test time and destination, then check the policy it used. Logs may reveal browsing destinations and other private information; remove sensitive details before sharing troubleshooting materials.
With Config, Check the Rule Result Too
With Config selected, visit one destination expected to use PROXY and another expected to use DIRECT, then check the available request records. Rules in a configuration are usually matched in order; a broad rule near the top can prevent a more specific rule below it from taking effect. A page loading doesn't by itself mean traffic was routed as intended—check the policy applied to each request.
To compare modes, stop the current test request, change Global Routing, and make the same request again; existing connections may keep using the handling they had when first established. Use the same page and network conditions, changing only one variable at a time. Once you've confirmed that the test responds, the page loads, and the policy matches your expectations, enable your own configuration or On Demand gradually. That makes changes easier to diagnose.
05 · Common Issues and Troubleshooting Steps
When something fails, note where you got stuck. A failed subscription update, a VPN that won't connect, a timed-out Connectivity Test, and one page that won't load aren't necessarily the same problem. Keep a record of the reproducible destination, network type, server name, and Global Routing mode. Don't include a full subscription URL, password, or authentication details in a public report. Work through the checks below in order, retesting after each one.
Subscription List Not Expanding? Check the Update
Confirm that your device's current network can load regular webpages, then check that the URL saved in Subscribe is complete. If updating the subscription requires a connection you haven't established yet, first confirm whether you already have another working way to connect. An empty list isn't a server selection problem. Expired URLs, account changes, or a response that doesn't match the subscription format need to be checked with your provider. Saving the same incorrect URL repeatedly won't create working entries.
Test Times Out? Check Settings and Network
Open the server entry for editing and compare Type, Address, Port, and authentication fields with the original details. Check TLS, transport settings, and related name fields too. Look for spaces at either end, incorrect port numbers, and easily confused characters. Don't mix parameters from two entries just because their names look similar. For connections that rely on time validation, check the device's date, time, and time zone in system settings.
If the settings match but the test still fails, try switching between Wi-Fi and cellular, if available, using the same server and test method. If only one network fails, focus on that network's connectivity. If both fail, check whether the server is available. The test method itself may also be restricted by the destination, so check real-world page access too rather than drawing conclusions from a timeout alone.
Switch Won't Stay On? Check System Settings
Check whether you've approved the VPN configuration and whether another connection is taking over the system VPN. Search for VPN in Settings to check the configuration status, but don't make deleting a profile your first step. If you need to authorize it again, keep your server and configuration details in the app, follow the system prompts, then return to Home and connect. App data, the system VPN configuration, and the remote server are separate layers; removing one won't necessarily resolve issues in the others.
Connected but Some Destinations Fail? Check Routing and DNS
First make sure Global Routing isn't set to Direct. If Proxy works but Config doesn't, check the active Config file, rule order, and matched policy. A DNS lookup failure can look like a server timeout. Use connection records, if available, to determine whether the failure occurred during name resolution or while connecting to the remote server. Avoid changing DNS, rules, and servers all at once, or you won't know which change helped.
Change only one field or routing mode at a time. Save, retry the same request, and restore the original value if it doesn't help before checking the next item. For more detail, read Frequently Asked Questions about purchases, permissions, and subscriptions, or see the Rules and Configuration Reference for configuration structure. By now, you should be able to distinguish missing imported details, an unreachable server, missing local authorization, and unexpected rule behavior—without repeatedly reinstalling the app to troubleshoot.