Shadowrocket Setup Guide
Import a Subscription and Verify the Connection

Step 01 · Identify Your Details

Add a Server or Import an Existing Subscription

Identify what you have before choosing an import method. A subscription link usually provides a group of servers and may support future updates. A single-server share contains details for one connection. Manual settings must be entered field by field, including the protocol, address, port, and authentication details. Don’t assume something is a subscription just because it looks like a URL. Follow the instructions from your service provider so you don’t enter a documentation page, account page, or configuration download link in the wrong place.

Subscription link: Find Subscribe in Config

Open Shadowrocket, go to Config, and find Subscribe. Open the form to add a subscription, enter a recognizable name, paste your complete subscription link into the address field, then save and wait for it to load. The name is for identifying it on this device and doesn’t change the subscription. The path and query parameters in the link may be used for authentication, so don’t remove or rearrange them.

When loading is complete, return to Home and check for the server group or entries. Seeing a list means the client has read the details, but it doesn’t confirm that every server is available. Select the server you intend to use before testing the connection. If the list is still empty after saving, check that the link is complete and look for an update error. Don’t add the same details repeatedly.

Manual settings: Use Add Server from Home

If you have individual settings, tap the add button on Home and open Add Server. Choose the protocol specified in your details, then enter the server address, port, and authentication fields. Required fields vary by protocol: some use a password, while others use a UUID. Fields from different protocols aren’t interchangeable. Choose any name or note you like, but enter the connection details exactly as provided.

If the address field expects a hostname, enter only the hostname from your details—don’t add a webpage path. Enter the specified port. Set TLS, transport, Host, SNI, and other fields only when your details call for them. Don’t enable every option just because it seems more complete. After saving, return to Home, select the new entry, and reopen it to check that you haven’t pasted line breaks, spaces, or other explanatory text along with the settings.

QR codes and clipboard imports: verify the details afterward

If you have a QR code for a server, use Scan QR Code, allow camera access when prompted, and scan a QR code you own. For a clipboard import, copy the complete share and use the client’s import option. QR codes and clipboard imports reduce manual entry; they can’t supply missing details or guarantee that a server is currently reachable.

After importing by any method, return to Home and confirm that the entry name, protocol, and server address look right, then select it. Treat subscription links, passwords, and complete shares as sensitive information. When troubleshooting, record only the error message and field names—not the full details. Next, check Global Routing; don’t turn on the connection just yet.

Step 02 · Choose How Requests Are Handled

Choose a Global Routing Mode

Find and open Global Routing from Home. Check whether Config, Proxy, or Direct is selected. The server determines which connection details are used; Global Routing determines how requests are handled. If you switch servers without checking this setting, you may think requests are going through the selected server when they aren’t.

First test: reduce the variables

For your first connection, if you want to check whether the server you just imported works, temporarily select Proxy. This reduces interference from configuration rules. If basic requests still fail, check the server details or network before changing a large number of rules. Proxy doesn’t mean every app or all system traffic will be handled in exactly the same way. After connecting in the next section, test the apps you actually use.

Once the server works, switch back to Config to handle requests according to their destinations. In Config, check which configuration is active so you don’t confuse an imported configuration with an enabled one. Only the active configuration affects current rule handling; editing a different file won’t automatically change the rules in use.

Config: Check the active file, then review the rules

Rules are generally evaluated from top to bottom, and the matching rule’s policy is applied. PROXY sends a request through the proxy policy, DIRECT connects directly, and REJECT blocks the request. FINAL is the fallback when no earlier rule matches. When first using an existing configuration, don’t change rules, switch servers, and adjust DNS all at once. If the result changes, you won’t know which setting caused it.

Use Direct to compare against your regular network while troubleshooting, not to test the proxy route. After choosing a mode, return to Home and make sure the same server you just checked is still selected. The client now knows which server details to use and how to handle requests. Next, turn on the connection and complete system authorization.

Step 03 · Authorize the System Connection

Turn on the switch and check the connection status

Return to Home and confirm that the selected server and Global Routing mode match your choices, then turn on the connection switch at the top. The first time, iPhone or iPad may show a system prompt to add a VPN configuration. Confirm that the prompt is for Shadowrocket, allow it, and complete any passcode or biometric verification required by your device. This step is handled by the system; you don’t need to enter your device passcode on a website.

After authorization, return to Shadowrocket and check whether the switch stays on. If it turns off immediately or the system prompt wasn’t completed, resolve the authorization issue first; you don’t need to delete the subscription right away. If you didn’t see the expected prompt, check the VPN configuration status in system Settings, then try again. Organization-managed devices may also be restricted by management policies; follow your device administrator’s instructions.

An enabled connection switch doesn’t mean the destination is reachable

When the system accepts the VPN configuration, it means the client can establish a connection environment for handling traffic. It doesn’t confirm successful server authentication or guarantee that every destination is reachable. Status-bar indicators can vary by device and display context, so don’t judge the connection only by whether an icon remains visible. Next, keep the current server and routing mode, run a test, and open the destination page.

During initial troubleshooting, don’t enable another VPN connection that could change the network route, or add automation such as On Demand. A clear, manual connection state makes it easier to see when the switch turns on and where a failure occurs. If other network configurations are already present, note their status first, then check which one is active in the system.

If you need to change servers, finish the current test and record its result before switching to one other entry and testing again. Change only one setting at a time. When you’re done, turn off the switch from Home. Before reconnecting later, check the selected server and Global Routing mode again instead of assuming they’re unchanged from the last successful session.

Step 04 · Test Real Requests

Verify Connectivity Test and app access

Run Connectivity Test first, then check a real webpage and the app you want to use. A test reflects one specific method and destination; it doesn’t provide a definitive result for every request. If a test succeeds but an app fails, or a test times out while some pages load, investigate the request’s route instead of declaring all the details valid or invalid.

Test the selected server, then open the same webpage

Find Connectivity Test on Home and run it. Wait for the test to finish and note the success or failure for the selected server. Different test methods may measure different things, so don’t treat a value in the list as actual download speed or switch servers based only on the number. For a first check, focus on whether the test completes consistently under the same conditions and whether real requests receive normal responses.

Then open a browser and visit a regular webpage you’re authorized to access, with content you can recognize. Check that the page text and necessary resources load—not just that the page looks like one already in the cache. Reload it, then try another page as a cross-check. Keep the same server selected so you can compare the test and browser results.

Test the target app and check which rules match

Once the browser works, open the app you intended to use and perform a specific action, such as refreshing a list or opening a new page. An app may request multiple domains. A working home page doesn’t prove that sign-in, images, or other features use the same route. If only one feature fails, note the exact action and message, then troubleshoot that request.

In Config mode, check the destinations and policies shown in the connection logs to see whether requests are handled as expected. If a destination matches DIRECT, it’s connecting directly according to the rules—not “failing over” because the server stopped working. If it matches REJECT, first check what the active configuration’s rules mean. You need to identify the actual policy to tell a connection issue from a rule-selection issue.

Changes in upload and download traffic in Data can help confirm that requests are being made, but an increase alone doesn’t prove the destination returned content successfully; background tasks can also generate traffic. Assess Connectivity Test, the actual page result, the routing policy, and Data together rather than relying on the switch or one number. After confirming access in Proxy mode, switch back to Config and repeat the same checks to identify differences caused by the rules.

Step 05 · Start with the First Failed Step

Common failures and how to troubleshoot them

Start troubleshooting at the earliest step that didn’t complete. If the details haven’t imported, fix the import first. If the connection switch won’t stay on, resolve system authorization. If the switch is on but a page won’t load, check the server and routing. Don’t skip straight to reinstalling, or change the protocol, DNS, rules, and server all at once. After each change, repeat the same test on the same page so you can tell whether it helped.

Import fails or the server list is empty

First confirm that you copied a subscription link or a share the client can recognize—not a documentation page address. Check for missing trailing parameters, spaces or line breaks, and whether the provider has changed the address. If a subscription update reports an authentication failure or unsupported content, ask the provider of your existing details to confirm what the link is for and whether it’s still valid. Repeatedly tapping Update won’t fix an incorrect address or restore missing access.

If the server list is present but new entries are missing, distinguish between refreshing a subscription and adding a server again. Update the existing subscription first, then check its group to avoid duplicate entries and accidentally selecting an old one. Manually added servers aren’t corrected by subscription updates; if their settings change, check each field against the new details.

Connectivity Test fails or there’s no response after connecting

Turn off the connection switch and check whether your regular Wi-Fi or cellular network can load a webpage. If a public network is still showing its sign-in page, complete its required login before returning to Shadowrocket. If the underlying network isn’t working either, fix the device’s basic network connection before changing proxy settings.

Once the basic network works, recheck the protocol, server address, port, and authentication fields. For settings that use TLS, make sure the relevant hostname matches your details and that the device’s date and time are correct. Don’t bypass errors by disabling certificate verification at random. If you have more than one server, test a different one while keeping all other settings unchanged, then ask your service provider to check the exact error message.

The switch turns off immediately or authorization is incomplete

Check whether the system refused to add the VPN configuration, authentication was completed, or another VPN connection is active. In system Settings, only change configurations whose purpose you can identify; don’t delete other network settings in bulk. If the device is managed and restricted, follow its management policy instead of repeatedly reinstalling the app.

Proxy works, but some requests fail in Config

First check the active configuration and the policy actually matched. Return to Config, confirm which file is in use, then check whether an earlier rule matches the destination and what policy FINAL uses. Rules are generally applied on the first match; a broad rule higher up can prevent a more specific rule below it from taking effect. Start with one specific request instead of clearing all rules to fix a single page.

If only Wi-Fi or cellular fails, keep the same server and routing mode, switch networks, and compare the results. If only one app has a problem, reopen it, repeat a specific action, and check the connection logs; a working browser doesn’t prove that every app will work. For more on protocol fields and choosing between options, see the protocol handbook. For rule order, read Rule Matching and the FINAL Fallback.