Shadowrocket
Import a Subscription and Connect for the First Time

01 Add a Server or Import an Existing Subscription

First, identify what information you have: a subscription URL, server sharing details for a single server, or server parameters to enter manually. Each uses a different import method, so you don't need to try every option with the same information. A subscription typically retrieves and updates a set of server entries; details for a single server create one connection entry. A subscription is not a rules configuration file, so check Global Routing in the next step even after importing successfully.

Have a Subscription URL? Add Server → Subscribe

Open Shadowrocket, go to Home, and tap the add button in the upper-right corner to open Add Server. Under Type, choose Subscribe, then paste your complete subscription URL into the URL field. You can add a note to help identify it. Keep the URL unchanged, especially the parameters after the question mark. Check that you haven't included leading or trailing spaces, line breaks, or text from a chat message. Save using the control in the upper-right corner, then return to Home and wait for the result.

After importing, the relevant group or server entries should appear on Home. Check that the entries actually show up; a saved subscription name alone isn't enough. Saving a URL doesn't mean its remote content was retrieved successfully. If you see a group but no selectable entries, check whether your current network can access the URL, whether it's still valid, and whether the provider returned a recognized subscription format. Don't change URL parameters at random just to make entries appear.

Have Details for One Server? Enter Its Parameters by Type

If you have a server address, port, password, and protocol parameters, open Add Server on Home and choose the correct Type first. For example, if the details specify Shadowsocks, select that type before entering them. Don't choose a different protocol just because the address and port are the same. The fields vary by Type, so enter the authentication details, encryption method, and applicable transport settings exactly as provided. Don't guess at optional parameters that weren't supplied.

If you have a QR code, use Scan QR Code to import your own server sharing details and grant camera access when prompted. After importing, open the entry and check its Type, address, and port. A successful scan doesn't guarantee that the server is usable. If entering the details manually, save and return to Home, confirm the new entry appears, then select it as the server to use. Test one server at a time so you can track the results.

Subscription URLs and server authentication details may contain credentials. Don't post a complete URL, password, or QR code publicly while troubleshooting. You can share the error message and field names, but hide the actual values. After importing, decide how requests should be handled before changing other Settings. For the differences between subscriptions, server entries, and configuration files, see the Glossary.

02 Choose a Global Routing Mode

Return to Home and open Global Routing. First, learn the three modes: Config, Proxy, and Direct. This setting determines the overall routing method; the server selected on Home determines which connection details are used when a server is needed. These settings do different things, so selecting a server does not mean every request will pass through it.

Config: Check Which Rules File Is Active

Config handles requests according to the rules in the current configuration file. If you already have a rules configuration from a source you trust, open Config and check which file is actually active—not just whether it's listed. Then return to Global Routing and select Config. Rules may route different requests to PROXY, DIRECT, or REJECT, so different results for different destinations don't necessarily mean the connection is broken.

If you have only a subscription URL and haven't chosen a rules file, don't assume importing the subscription automatically sets up the routing you need. Check the current Config contents and their source before deciding whether to use those rules. Rules are evaluated from top to bottom, and an earlier match affects what happens next. For your first connection, there's no need to edit rules one by one; keep the original configuration intact so you can trace changes. For rule keywords and policy details, see the Glossary.

Proxy and Direct: Understand the Request Path

Proxy sends general requests through the currently selected server. During initial troubleshooting, this can temporarily reduce the variables introduced by rule-based routing. If you're unsure whether Config is affecting access to a destination, note the current mode, temporarily select Proxy, and test the same destination. This can help check the selected server, but it doesn't mean Proxy is required for everyday use or guarantee access to every destination.

Direct connects general requests to their destinations without using the selected proxy server. It can help you check direct access on your current network, but it doesn't verify that the server works. If you're testing in Direct, a page loading successfully doesn't mean the selected server on Home was used. After choosing a mode, return to Home and note the selected server and Global Routing setting. Turn on the connection switch in the next step.

03 Turn on the Connection Switch and Approve the System Prompt

On Home, confirm the selected server and Global Routing mode, then turn on the connection switch at the top of the screen. The first time you connect, the system may ask to add a VPN configuration. This allows Shadowrocket to create the required network configuration; it doesn't add another subscription or fill in missing server details. Confirm that the prompt matches the action you just started, allow the configuration, and complete any device authentication the system requires.

If you previously denied the prompt, the connection usually can't continue. Try turning the switch on again in Shadowrocket and check whether the system displays the authorization prompt. You can also check the VPN configuration status in system Settings. Don't delete multiple unfamiliar configurations in an attempt to restore the connection. On a managed device, first check whether an organizational policy applies. Repeatedly switching servers won't resolve a missing-permission issue.

After approving the prompt, return to Home and check whether the switch stays on. Wait for the connection status to settle. If the switch turns off immediately, note any message and check that the selected entry is complete, the system configuration was created successfully, and no other VPN connection is active. If the switch stays on, continue with verification: the system's VPN status only indicates the state of the system connection configuration. It doesn't prove that server authentication, destination access, or rule matching is correct.

For this round, keep the process manual. Don't enable On Demand or change multiple Settings at once. To try another server, turn off the connection first, select a different entry, and turn it back on so each test has clear inputs. On iPad, follow the same sequence: Home, server selection, Global Routing, and the connection switch. The layout may vary by device and app display, but the items to check remain the same.

Once the switch stays on, check how real requests behave. Don't focus on test numbers yet. First confirm that the selected entry, routing mode, and actual access result are consistent.

04 Verify That the Connection Works as Expected

On Home, use Connectivity Test to test an existing server, and note the test method. A response means the test returned a result under those conditions; it doesn't mean every website, protocol, or rule will work. A timeout must also be considered in the context of the test destination and current network. For your first verification, keep both the test result and the page access result rather than drawing conclusions from a single number.

Check These Three Things in Order

1. Confirm that the server currently selected on Home is the one you just tested. After updating a subscription or switching servers manually, check the selection again so you don't test one entry and connect through another.
2. Open a page you can normally access to confirm that basic network requests work on the device, then visit the destination whose routing path you want to verify. Refresh the page or open a new one so you aren't relying on cached content.
3. Return to Shadowrocket and review any available connection records in Data alongside the current Global Routing mode and rules in Config. The details shown may vary; rely on what the app actually displays, and don't treat a missing field by itself as an error.

With Config selected, two destinations may match different rules, such as DIRECT and PROXY; interpret the results in light of those rules. To compare, switch temporarily to Proxy and test again without changing the server or destination. If Proxy works but Config doesn't, check the rules and corresponding policies first rather than immediately re-entering the server password. Restore your intended mode after comparing so you don't leave a test setting in place for everyday use.

If Connectivity Test responds but pages keep failing to load, don't assume the issue is simply slow speed. Authentication, transport parameters, DNS resolution, the destination itself, and routing rules can all affect requests. First check whether every destination fails or only one, then decide what to investigate. One failed page doesn't describe the entire connection, and one successful page doesn't prove all routing is as expected.

Once verification succeeds, note a repeatable set of test conditions: the server, Global Routing mode, destination, and network in use. Use the same conditions to retest after changing Config or enabling On Demand. You don't need to save passwords or complete subscription URLs—just enough information to identify the entry and steps you followed.

05 Troubleshoot by Identifying Where the Process Fails

When something goes wrong, first identify where the process stopped: the information didn't import, the server test returned no result, the switch won't turn on, or access doesn't work as expected after connecting. Change one thing at a time, then repeat the same test. Changing the subscription, server parameters, Global Routing, and DNS all at once can erase useful clues and make it hard to tell which change helped.

Subscription Saved, but No Server Entries Appear

First, check that the URL is your complete subscription URL, then confirm that your current network can access it. A login page, error page, or response in the wrong format isn't an importable subscription, even if it loads. If you had working entries before, don't clear everything as soon as an update fails. Keep the existing entries and check the URL and service status. If you contact the original provider, describe the error and where it occurred without sharing the complete URL. For more details, see the subscription import section in Frequently Asked Questions.

Entry Is Present, but Connectivity Test Times Out

Open the entry and compare its Type, server address, port, authentication details, and transport parameters with the original information. Check digits, capitalization, and spaces copied accidentally. If the entry is managed by a subscription and you've edited it manually, a later update may change those values; first confirm where the current values came from. Then compare it with another server you already have. If only one fails, check that entry and its service status first. If all fail, also check whether the device's current network is working.

Switch Turns Off Immediately or Authorization Wasn't Completed

First, check whether you allowed the system prompt to add a VPN configuration, then check whether the entry is missing required fields. If another VPN connection is active on the device, confirm what it's for and disconnect it if it's not needed before trying Shadowrocket. Follow the management requirements on managed devices; changing server details won't bypass them. A switch that won't stay on and a switch that stays on while pages fail are different issues and require different checks.

Connection Is On, but No Pages Load

Turn off the connection first and check that your current Wi-Fi or cellular network can access a basic page. Then reconnect and test the same destination. If Direct works but Proxy fails, check the selected server and authentication parameters first. If Proxy works but Config fails, focus on the configuration file, matched rules, and related policies. DNS can also affect results, but don't switch to an unfamiliar address right away. Keep the current settings and first check whether the issue is limited to domain name resolution.

Only Some Destinations Fail, or the Connection Changes by Itself

For destinations that behave unexpectedly, note the destination and current mode, then check whether it matches the expected PROXY, DIRECT, or REJECT rule. After a subscription update, entry names or available servers may change, so confirm which entry is selected. If the status changes when you switch Wi-Fi, lock the screen, or open an app, check the On Demand trigger conditions. Turn off automatic triggers and compare with a manual test first; don't reset all configurations. For a systematic check of rule order, DNS, battery use, or issues after an update, see the Troubleshooting Guide.

This completes the first-time setup. You don't need to add the server again for everyday use: check the selected entry and Global Routing mode, then revisit the relevant steps here if anything changes. For unfamiliar interface terms, see the Glossary. For purchase, restore, or installation questions, see App Store Purchase and Installation Guide.