1. Add Server / Subscribe: Add a server or import a subscription
First, identify what kind of details you have. Use subscription import for a complete link that updates a server list. To add a single server, enter its address, port, protocol, and authentication details. Both methods start from Home. Do not paste a subscription link into the server address field or submit plain server details as a subscription link.
Have a subscription link? Choose Subscribe
Open Shadowrocket and go to Home. Tap the add button in the top-right corner, then open Add Server. Under Type, choose Subscribe. Paste the complete subscription link into URL and enter a recognizable name under Remarks, such as “Personal subscription.” The name is for local reference only; it cannot fix the link or change the server. Before saving, check that the link’s beginning, path, and query parameters are complete, especially everything after the question mark.
After saving, return to Home and wait for the subscription request to finish. Check that server entries appear in the corresponding group. Seeing the subscription name without any entries in the group does not mean the import succeeded. First check whether an update is still in progress or an error appeared, then compare the link with the original. Some subscription URLs display plain text or encoded content in a browser; a page without standard web formatting does not necessarily mean the link is invalid.
If you received the details in a message or document, watch for trailing spaces, line breaks, punctuation changes, or truncated parameters when copying. Subscription links often contain access credentials; do not include the full URL in public screenshots, comments, or test logs. To check whether a subscription is valid, use your existing service channel rather than repeatedly creating the same subscription.
Have details for one server? Enter each field for its protocol
Open Add Server and select the protocol specified in your details, then enter the server address, port, and authentication fields. Required fields vary by protocol: passwords, identifiers, transport options, and TLS settings are not interchangeable. Enter the original details as provided. Do not leave an unfamiliar field blank or copy a value from another server.
The server address field usually takes only the supplied hostname or IP address. Enter the port in its own field; do not paste a full web URL with a path. If you have an importable server link or a QR code, you can use the corresponding import option or Scan QR Code. After importing, open the entry and check its protocol, address, and port rather than relying on the name alone.
After saving, return to Home and select the server you want to use. Check the selected indicator. Having multiple entries in the list does not mean they will all handle requests at once. For your first test, choose one server and note its name; use that same entry for subsequent tests and browsing. Leave On Demand off for now so automatic connection conditions do not interfere with manual testing.
2. Global Routing: Choose a routing mode
After importing a server, decide how requests should be handled. Open Global Routing from Home and check the current selection. The three modes are Config, Proxy, and Direct. They change how routing decisions are made; they cannot fix a server password or make an invalid subscription work again.
Config: Let the active configuration determine the policy
Config handles requests according to the rules in the active configuration. Open Config, confirm which file is actually enabled, and review its rules and policies. Importing a server subscription alone does not mean that appropriate routing rules are in place for every destination. Server lists and rule configurations serve different purposes, so check them separately.
When reviewing rules, check the match conditions, their order, and the final action. DOMAIN-SUFFIX matches domain suffixes; IP-CIDR matches IP address ranges; FINAL applies a policy when no earlier rule matches. The example below illustrates rule syntax and is not a complete configuration to import. example.com is a sample domain, not a real test destination.
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXYPROXY and DIRECT are policy keywords, not server names. PROXY sends traffic to a proxy policy; DIRECT connects without a proxy. If a rule or policy group specifies another option, check which one is actually selected. The presence of a rule alone does not prove that it will match a request: earlier rules, the active file, and the request’s domain can all affect the result.
Proxy: Check the proxy connection separately
Proxy sends applicable traffic through the current proxy policy. During initial troubleshooting, you can use this mode briefly to check whether the server works separately from whether rules match as expected. It does not prove that every app will behave the same way; system traffic coverage, the current network, and the destination service can all affect access. Switch back to Config when you are done if you want rule-based routing.
Direct: Check direct access as a baseline
Direct connects without a proxy; it does not prove that the proxy connection is working. Use it to check whether the current network can reach a destination directly. If a page opens in Direct mode, that only confirms that direct access worked for that test; it does not validate the server settings. Before connecting again, review Global Routing so you do not mistake a temporary test mode for your final setting.
3. Home: Connect and authorize the system
Return to Home and check the selected server, Global Routing mode, and current network in that order. For your first test, keep the network unchanged—for example, complete a test on the same Wi-Fi before testing cellular data separately. Do not repeatedly toggle the connection before selecting a server, or change the server, network, and rule file at the same time; otherwise, it will be difficult to tell what caused a failure.
Turn on the connection switch at the top of Home. The first time you connect, the system may ask to add a VPN configuration. This authorization is required for the app to establish a system network connection. Read the app name and description in the prompt, make sure it was triggered by this action, and then confirm and authenticate as requested. Complete authorization in the system interface; do not enter device unlock information or Apple Account credentials in a server entry.
Return to Shadowrocket and check whether the switch and connection status stay on. If the switch immediately turns off, first check whether system authorization was canceled, a prompt is still pending, or another VPN configuration is active. You can review the VPN status in system Settings, then return to the app and try again. Do not delete system configurations with an unclear purpose just to keep the switch on.
An established connection means the system connection channel has started; it does not prove that the selected server can reach every destination. An incorrect password, port, or transport setting can still cause requests to fail. Test the connection in the next section as soon as authorization is complete instead of treating the status bar indicator as a final result. Status bar displays can vary by device and system interface, so check the connection status in both the app and the system.
When you finish this test, turn off the connection switch on Home and confirm that the system connection has ended. If it reconnects automatically later, check whether On Demand is enabled. Keeping automatic connection conditions out of the process until the first manual test is complete helps prevent confusion when a connection turns back on after being disabled.
4. Connectivity Test: Verify that the connection works
There are three separate checks: whether the server test returns a result, whether the system connection is established, and whether actual requests use the intended policy. Each answers a different question, so one cannot replace another. First, run Connectivity Test on the selected server from Home. Once the result settles, try accessing a destination. Do not switch entries during the test and then attribute the earlier result to a different server.
Connectivity Test results depend on the test method and destination. A response only confirms that particular test received a response; it does not mean every website or app will work. A timeout also needs to be assessed in context—you cannot conclude that every server is invalid from one result. For your first test, focus on the selected entry instead of comparing results across the whole list.
Next, open a browser and visit a page you know is usually accessible on your current network, then try the destination whose routing policy you want to check. Make a fresh request each time; do not rely on an already loaded page or cached content. Record the destination, network, server, and Global Routing mode. That is more useful for troubleshooting than simply noting “works” or “doesn’t work.”
In Config mode, check any available connection records under Data for the request you just made, including its destination, rule, and policy. The information shown may vary by record; do not guess if policy details are unavailable. Confirm that the active configuration is in use and that the request’s DIRECT, PROXY, or other configured policy matches your expectations.
If access works in Proxy but not as expected in Config, check the rule order and policy selection in Config first. Do not immediately change server authentication settings. If both modes fail but the comparison page opens in Direct, continue checking the server and connection path. This comparison can narrow down the cause, but conclusions still depend on the destination and error details.
5. Common issues: Troubleshoot in order
Start with the earliest step that failed. If the server list is empty, fix the import first. If an entry exists but its test fails, check the server details. If only some destinations fail after connecting, investigate the rules and destination access. Keep the original configuration and entries, change one item at a time, then retest and record the result. Repeatedly deleting entries, importing them again, and changing rules can turn a simple issue into one that is hard to reproduce.
Subscription saved, but the server list is empty
Open the Subscribe entry and check that the URL is complete. Make sure you copied a subscription URL, not an account or information page. Check whether the update finished and whether your current network can reach the URL, then use your existing service channel to confirm the subscription status and contents. If the update returns an error or no content, adding the same link again usually will not help. First determine whether the failure occurred during the request or while parsing its contents.
If the list had working entries before the update, keep them rather than deleting everything to retrieve the list again. Note whether the failure happened after a manual update, a network change, or reopening the app; this can help identify whether update timing is involved. For more troubleshooting steps, see how to troubleshoot an empty server list after a subscription update.
Connectivity Test shows a timeout
First confirm that the test is using the selected server. Then check its address, port, protocol, authentication, and transport settings one by one. Verify the device’s date and time; an incorrect system time can cause failures, especially when TLS or time-based authentication is involved. Retest on a different network to distinguish an access network issue from a server issue. After switching networks, keep the same server and test destination.
Do not guess at new ports, disable authentication, or change TLS settings. Use the server details you already have, and confirm service status through your existing service channel. For a more detailed logging process, see troubleshooting server timeouts and connection failures and record results in order.
Connected, but webpages won’t load
First check that the underlying network can reach a comparison page. Rule out basic issues such as Wi-Fi requiring a sign-in or cellular data being unavailable. Then check Global Routing: in Direct, requests are not handled by a proxy policy; in Config, check the active file and matching policy. Investigate DNS settings only if you see a clear DNS-related error. Avoid changing the server, rules, and DNS settings at the same time.
If only one destination fails, compare it with another destination you know works and check the request record. Issues with the destination service, a mismatched rule, restricted server access, and authentication failures can produce different results; they should not all be attributed to “the app is disconnected.” If only one app has a problem, make a fresh request in that app and keep in mind that existing connections or cached content can delay what you see.
Results are confusing after changing settings
Return to the last state you clearly recorded: restore the original server, Global Routing mode, and configuration file, then turn off any On Demand conditions added during this test. Start again at the verification steps. Do not treat one temporary success as proof that the settings are stable. Repeat the test under the same conditions, then check performance separately after changing networks.
For troubleshooting notes, record only the time, network type, local server name, routing mode, and symptoms. Before sharing details with anyone, hide the full subscription link, passwords, keys, and other authentication fields. Check configuration snippets for the same information before sharing them. To review purchases, App Store access, or restoring purchases on a new device, see the installation guide. Do not confuse an app acquisition issue with a connection problem involving an existing server.