Official Guide / First Connection
Shadowrocket Setup Guide
Import an existing subscription → choose Global Routing → authorize the connection → verify access → troubleshoot issues. First establish a repeatable connection, then adjust rules and On Demand settings.
- Areas covered: Home / Config / Data
- Test a Manual Connection First
- Change One Setting at a Time
STEP 01 / Import Existing Details
Add Server: Add a Server or Subscribe
First identify what information you have, then choose the right option. A subscription URL retrieves a list of server details; it is not the address of a single server. Details for one server usually include its protocol, address, port, and authentication parameters. Don’t mix up the two. Open Shadowrocket, go to Home, and tap the add button in the upper-right corner to open Add Server. Follow just the path that matches your details; there’s no need to add the same information twice.
Existing Subscription URL: Choose Subscribe
In Add Server, choose Subscribe under Type. Enter your full subscription URL in URL and add a label you’ll recognize. Before saving, check that the beginning and end are intact and that no line breaks, spaces, or chat text were pasted with it. Query parameters may be used for authentication, so don’t remove them to shorten the URL. Enter the URL used to retrieve your existing subscription—not a service information page or account login page.
After saving, return to Home and wait for the content to load. Check whether server entries appear in the relevant group. Seeing a subscription name doesn’t mean its contents have been retrieved: make sure the group expands and contains selectable servers. If the list is empty, keep any error message and check that the URL is valid and your network is working. Don’t immediately add the same subscription again. To update it later, refresh the existing subscription; you usually don’t need to add a new one each time.
Existing Details for One Server: Enter the Protocol Settings
In Add Server, choose the protocol specified in your details under Type, then enter the server address, port, and required authentication fields. The fields differ across protocols such as Shadowsocks, VMess, VLESS, and Trojan, so use the parameters you were given. Enter only the specified hostname or address in the address field; don’t paste a full subscription URL there. Don’t guess the protocol from its name or combine parameters from separate entries into a new record.
If your details include TLS, server name, or transport options, check those too; an address and port alone may not be enough. If you import existing connection details with Scan QR Code, check the parsed type and address after saving rather than relying on a successful scan. A QR code is just an input method; it doesn’t replace checking the parameters. If you don’t have clear instructions for a particular field, check the original details instead of changing encryption or authentication options at random.
This step is complete when Home shows a selectable server entry with a clear source and complete parameters. Note its label and group. Next, choose Global Routing to determine how traffic is handled after connecting. Leave On Demand off for now so automatic connection behavior doesn’t interfere with your first manual test.
STEP 02 / Choose Where Traffic Goes
Global Routing: Config, Proxy, and Direct
Adding a server doesn’t mean all your traffic will use it. Return to Home, tap Global Routing, and check the current mode. The three options are Config, Proxy, and Direct. Decide what you want to test before choosing one. An active connection and routing all traffic through the selected server are not the same thing.
| Mode | What It Does | What to Check First |
|---|---|---|
| Config | Handles requests according to the rules and policies in the currently enabled configuration. | Check the enabled file and traffic handling rules in Config. |
| Proxy | Routes traffic through the proxy path, useful for checking the server connection. | Confirm the selected server or relevant policy. |
| Direct | Routes traffic directly. | Useful for checking the basic network; it doesn’t confirm that a server is working. |
For Rule-Based Routing: Check Config First
To use a configuration, open Config and check which one is enabled, along with its rules and policies. Importing a subscription and enabling a configuration are separate actions: a subscription mainly updates the server list, while a configuration determines matching conditions and how traffic is handled. A server appearing in Home doesn’t mean it automatically replaces every server reference in the configuration. Before applying a configuration you don’t understand, check its source and contents.
For example, DOMAIN-SUFFIX,example.com,PROXY means that a matching domain suffix of example.com uses the proxy handling specified by PROXY. IP-CIDR,192.168.0.0/16,DIRECT routes the matching address range through DIRECT. These are examples of rule syntax; you don’t need to copy them into your configuration to complete this guide. Rules are evaluated in order. Once a request matches an earlier rule, later rules may not apply.
Use Proxy Temporarily for Comparison, Then Restore Your Original Mode
To check whether an existing server can connect, temporarily use Proxy to reduce the effect of rule selection on the test. Note the original mode first, and make sure the server you want to test is selected in Home. Switch back to Config after the test. Direct is useful for checking whether the device can reach a target it could normally access; it isn’t a substitute for testing a remote server.
By the end of this step, you should be able to identify the current mode and the configuration or server in use. If you can’t, don’t change DNS and On Demand at the same time. For more on rule priority and policy references, see the rule-based routing guide. Keep the routing path clear for now, then move on to connecting.
STEP 03 / Connect Manually
Home: Turn on the Connection and Allow the VPN Configuration
Return to Home and check the selected server and Global Routing mode again. If server names are similar, identify the entry by its group and protocol too, so you don’t connect to the wrong one. When ready, turn on the connection switch at the top and check the status shown in the app. The first connection may trigger a system authorization prompt. Don’t mistake a brief change in the switch for a server error before authorization is complete.
First VPN Configuration Prompt
The system asks to add a VPN configuration so Shadowrocket can create a system connection to handle device network traffic. Make sure you initiated the connection in Shadowrocket, then follow the system prompt to allow it and complete any required device authentication. This is separate from adding a server: system authorization determines whether the app can establish a connection, while the server parameters determine whether communication can then succeed.
After allowing the request, return to Shadowrocket and check whether the connection continues. If you canceled earlier, the app hasn’t received the required authorization. Start the connection again and follow the prompt rather than repeatedly changing the server password. You can check the related configuration under VPN in system settings; the path varies by system version, so use Settings search to find VPN if needed. Don’t delete the system configuration as your first troubleshooting step, as this may make recovery more complicated.
Connection Status vs. Actual Access
A switch that stays on or a VPN status shown by the system means the system connection is established, but that’s not the final check. The selected server may be unreachable, a target may fail to resolve, or the current rules may route it directly. Continue testing with the current settings after connecting. Don’t stop at the status indicator or switch between multiple modes before you know the result.
During your first manual test, pause other configurations that manage VPN connections and keep the network environment consistent. If existing On Demand conditions trigger automatically, note them and pause automatic connections first. Otherwise, a manual disconnect may be followed by an automatic reconnect, which can look like the switch isn’t working. Don’t delete system settings you don’t understand just to make the test appear successful.
Record three basic details: whether you’re on Wi-Fi or cellular, which server is selected in Home, and the current Global Routing mode. That gives you clear test conditions to refer to if access fails. Once the connection is stable, add automation gradually; it’s easier to identify the cause than when changing several options at once.
STEP 04 / Verify in Layers
Connectivity Test and Real-World Access Checks
Check three things separately: whether the system connection is established, whether the selected server is reachable using the chosen test method, and whether the target is accessible as expected. None of these results replaces the others. Start with Connectivity Test in Home, noting the method used and the result for each entry. Then open your target in a browser or the app you normally use.
Read the Test Result, Then Check a Real Request
Connectivity Test results depend on the test method and target, your current network, and how the server handles the test. A number reflects the result of that particular test; it doesn’t guarantee that every website or app will work. Interpret timeouts in the context of the test target rather than assuming all communication has failed. When comparing two existing servers, use the same test method on the same network; otherwise, the results aren’t comparable.
For an access check, first open a familiar page that normally works, then try the target you actually need. If only one app fails, try opening the same service in a browser to distinguish an app-specific issue from a connection problem. Keep the target consistent between tests. Don’t switch pages each time or rely on an already-open page to judge whether a new connection works; cached content may not make a new network request.
Check Connection Records in Data
Open Data to review the requests or connection information currently visible, and look for an entry related to the target you just tested. Check whether the request appears, whether the domain or address matches your expectations, and which policy or route is shown. The fields available depend on the app. If there isn’t enough information, make a clearly identifiable new request rather than drawing conclusions from an unrelated historical entry.
When using Config, check whether the matched rule and handling match your expectations. If a target should connect directly but matches a proxy policy, check the enabled configuration and rule order. If it should use a proxy but matches DIRECT, first identify the rule it matched. Don’t simply change FINAL to a different route: an earlier rule may already have handled the request, so changing the fallback may have no effect.
The connection is verified when the status is normal, the target generates a new request and behaves as expected, and the visible route matches the selected routing mode. If you used Proxy temporarily, switch back to Config and test the same target again. Then, if needed, configure On Demand for your usage. See the On Demand settings guide for conditions and priorities.
STEP 05 / Troubleshoot One Variable at a Time
Connection Issues: Check from Network Basics to Rules
When something fails, note what happened before deciding what to check. A subscription that won’t load, a switch that won’t stay on, a timed-out test, and one inaccessible target are different problems and need different checks. Keep the current configuration and error message, change one condition at a time, and retest the same target. Work through these layers from the outside in to avoid repeating steps.
Layer 1: Basic Network and Subscription Content
Turn off the current connection first, then confirm the device can reach pages that normally work. If Wi-Fi requires network sign-in, complete that first. On cellular, check network service and the app’s network permissions. Resolve any basic network issue before continuing. You can compare Wi-Fi and cellular, but record each result separately rather than comparing tests made under different conditions.
If Subscribe updates fail, check that the URL is complete, the subscription is still valid, and your current network can retrieve it. A successful update only confirms that the list was retrieved; it doesn’t guarantee that every server entry works. A failed update doesn’t necessarily invalidate entries already saved. Check the specific message and your subscription details. Never share a full URL containing authentication parameters when asking for help publicly.
Layer 2: Server Parameters and System Authorization
If an entry is listed but its test fails, check the protocol, server address, port, and authentication fields one by one. For entries with TLS or transport options, confirm those parameters match the original details. An incorrect device date or time can affect secure connections, so check that too. If your existing subscription contains another server, you can test it under the same conditions for comparison, but don’t change unknown parameters in the original entry based on that result.
If the switch turns off as soon as you turn it on, or remains at the authorization stage, first check whether the system allows the VPN configuration and whether another connection setting is involved. Recreate the system configuration only if you’ve confirmed it was deleted or needs rebuilding, and follow the app’s prompts. Don’t confuse system authorization failure with remote authentication failure: the former usually occurs before a connection is established; the latter calls for checking the connection details and error records.
Layer 3: Routing, Rules, and DNS
If a target works with Proxy but fails with Config, check the active configuration, matched rule, and policy references first. If Direct works but the proxy path fails, check the selected server and remote connection. These comparisons help narrow down what to inspect, but don’t prove the cause. After switching modes, make a new request each time so an existing connection doesn’t affect the result.
If only some domains are inaccessible, use the information in Data to check DNS and the relevant target records. Don’t change DNS, disable authentication checks, edit rules, and switch servers all at once; even if access returns, you won’t know which change fixed it. For more on DNS behavior and interpreting specific errors, see Frequently Asked Questions. For App Store accounts, restoring purchases, and purchase verification, see the App Store access guide; you don’t need to revisit the purchase process while troubleshooting a connection.
You’ve now completed the first-use workflow: imported existing details, selected a routing mode, authorized the system connection, and verified a real request. Use the same method for future changes: record the original state, change one thing, then test the same target. For further setup, see the relevant section in the settings guide; there’s no need to repeat all the getting-started steps.