Shadowrocket Tutorial:
From Import to Connection Test

After opening Shadowrocket, stay on Home. Here you can view server entries, select the server to use, and control the connection. Tap the plus button in the top-right corner to open Add Server, then check Type before entering anything. Work out whether you have a subscription link that can refresh a server list or details for a single server, such as its address, port, and authentication parameters. These require different formats.

Have a Subscription Link? Select Subscribe

In Add Server, select Subscribe under Type and paste the complete subscription link from your own service provider into URL. Enter a name you will recognize, save, and return to Home while the list loads. If the subscription appears as a group, expand it and check for individual server entries rather than just a group heading. A subscription retrieves or updates a list; its name alone does not mean that a usable server is selected.

Check the link before and after pasting: make sure the beginning, end, and parameters are intact, with no extra spaces, line breaks, quotation marks, or text added by a messaging app. Do not use a service provider's website or account page URL as the subscription URL. The link may contain account information, so keep it on your own device. Do not share the full link when asking for help or include it in a shared configuration or screenshot.

Have Details for One Server? Fill Them In Under Type

If you have details for a single server, select the protocol specified by your service provider under Type, such as Shadowsocks, VMess, VLESS, or Trojan, then fill in the corresponding fields. Enter the address and port in their respective fields, and use the exact password and other authentication details provided. For additional options such as TLS, transport, or server name, follow the original details rather than guessing based on the protocol name. The same protocol does not mean all additional parameters are interchangeable.

If you have a QR code for import, use Scan QR Code to scan it. If the app requests camera access, review the purpose before allowing it. After scanning, check the imported type and key fields; seeing a name appear is not enough to confirm success. Manual entry, subscriptions, and QR codes are different ways to add connection details, but in every case, return to Home and check the actual server entry.

After saving, tap a specific server on Home and check that it is selected. A name is only for identification; it does not prove that the server works. Avoid importing the same details repeatedly, which can create similar entries and make it hard to tell which one you are testing. If the list is still empty, go straight to Step 5: Troubleshoot Import Issues. If a server is visible and selected, continue to Global Routing.

Return to Home and tap Global Routing to see the current mode. The three modes are Config, Proxy, and Direct. These are neither server groups nor protocols; switching modes will not usually fix incorrect import details. When getting started, note which mode you selected and use it as the basis for each test to avoid mistaking a mode difference for a server failure.

For Everyday Rule-Based Routing: Check Config

To route requests according to rules, select Config, then open the Config tab at the bottom and check the configuration file in use. The Config tab manages configuration files, while Config under Global Routing is a routing mode. They share a name but serve different purposes. Selecting a file is not enough: make sure Global Routing is also set to Config, or the observed behavior may not come from that file's rules.

Rules are generally matched from top to bottom, and the corresponding policy is applied when a rule matches. PROXY, DIRECT, and REJECT are different policies, not values to enter in a server address field. This page covers the initial connection; you do not need to write custom rules yet. For configuration sources, rule order, and the FINAL fallback, continue with the Complete Guide, from Beginner to Advanced.

Switch to Proxy or Direct Only to Isolate an Issue

If a destination behaves unexpectedly in Config, temporarily select Proxy and retry the same destination without changing the selected server. This helps narrow down whether rules are involved. Direct provides a comparison by attempting to reach the destination over the current network without the selected proxy server. Switching modes is not a universal fix; Proxy will not correct incorrect server authentication details. After testing, restore the intended mode, make a new request, and continue to the next step.

Return to Home and make one last check: the selected server is the one you just imported and intend to use, and Global Routing shows the intended mode. Then turn on the connection switch at the top. The first time you connect, your iPhone or iPad may show a system prompt to add a VPN configuration. This authorization allows the app to create the relevant network connection configuration. It does not ask you to buy the app again, nor does it confirm that a subscription imported successfully.

If the prompt appeared after you turned on the switch, check the app name and prompt, tap Allow, and complete device verification as required. Return to Shadowrocket and check whether the switch stays on and the connection status changes. If you already authorized the configuration, starting a connection later may not show the same prompt again. No prompt does not necessarily indicate a problem; do not repeatedly delete the configuration just to make the prompt appear again.

If you previously tapped Cancel, the app may not be able to connect. Try turning on the switch again and watch for the system prompt. If you still cannot proceed, open Settings and search for VPN to check the relevant configuration and authorization status. The location of system settings can vary with the interface, so follow what you see on your device. Stop the connection before making changes; do not delete or edit a configuration while it is connecting.

For initial testing, keep only the VPN connection you need active. Another VPN configuration that is connecting or reconnecting automatically may make the current status harder to assess. Stop any other active VPN connections, then return to Home and try again. Do not change the server, mode, and system configuration all at once. You do not need to enable On Demand yet; first establish a repeatable result with a manual connection, then consider automatic connection conditions.

Once the switch stays on and the system shows the corresponding connection status, continue to testing. A connection being established means only that the local connection process is active; it does not confirm that remote authentication, name resolution, or access to the destination has succeeded. Do not stop at the status icon—test with an actual request. If the switch turns off immediately or the status keeps changing, check authorization and configuration in Step 5 instead of rapidly toggling the switch.

First, use Connectivity Test on Home and check the result for the selected server. If the list has multiple entries, make sure you know which one the result belongs to; a successful result for another entry does not confirm that the selected server works. If the test gets no response, check the current network and server details. If it does get a response, continue by testing access to the actual destination—these checks address different things.

Connectivity Test results depend on the test method, destination, and network conditions at the time. A response does not guarantee that a request to a specific website, name resolution, or the required transport will work. Likewise, a single failed test does not mean that all access will fail. Repeat the test once with the same server and mode, then cross-check with actual access. This is more informative than repeatedly switching between different entries.

Test with a New Request, Not Just an Old Page

Open a browser and visit a destination you need to access, then reload the page or open a new one to generate a fresh network request. A cached page may display without a new connection, and an existing connection may continue using its previous handling. After changing Global Routing or the server, make a new request. If necessary, close the old page and reopen it so the result from before the change does not affect your assessment.

If you are using Config, check the request or connection logs to see whether the destination matched the intended policy. A request handled by DIRECT does not automatically mean routing is wrong; first check whether the configuration is supposed to send it direct. Similarly, selecting a server does not mean every request will use it. Note the destination, current mode, and actual handling before deciding whether to inspect a rule.

Use Data to Help Monitor Traffic

Open Data at the bottom and compare traffic before and after your action to see whether activity occurred. An increase in traffic is supporting evidence only; it does not prove that a specific destination used the intended policy, since other requests on the device may also generate traffic. Also confirm that the destination is accessible and that the current mode and relevant logs match your expectations.

Complete at least one short cycle: connect, make a request, check the result, and repeat the request to confirm it is reproducible. If needed, repeat the same test after switching between Wi-Fi and cellular to check for network-specific issues. If it fails on only one network, note that difference and use it to guide troubleshooting. If the result is stable, keep the working settings rather than making unnecessary changes.

The List Is Empty After Import or Parsing Failed

First, confirm that you entered a subscription URL, not an account or information page URL, and check that the link is complete. Repeatedly saving the same link usually will not help if it has expired, the service status has changed, or the response is not a valid subscription. Check the link status and original details with your own service provider. If you need a replacement link, update the old value before refreshing to avoid keeping multiple groups with similar names but different contents.

Next, check whether the device can reach the link when refreshing the subscription. Refreshing a subscription and using a server to access a destination are separate processes, and the existing connection status may also affect refreshes. Keep any currently working entries rather than clearing the list. Check the network conditions, retry the update, and note the exact message. If the old entries are still visible but the update failed, investigate the refresh issue first; seeing the old list does not mean you have the latest content.

A Server Entry Is Present, but Connectivity Test Fails

First, check which entry is selected, then verify its address, port, protocol, and authentication details. With manual entry, watch for similar-looking characters and missing fields. With an imported subscription, check the status of the associated service and whether the entry is still active. If you have another existing server available, compare it under the same network and test conditions. Do not change every entry's details at once, or it will be difficult to understand the results.

The Connection Switch Will Not Stay On

Start by checking system authorization. Confirm that the prompt to add a VPN configuration was completed, and check whether another VPN connection is taking over or automatic connection conditions are causing the status to change repeatedly. Use a manual connection as your baseline and temporarily pause related automatic connection settings before trying again. If an error still appears, record its exact text and what triggered it. A switch turning off alone does not prove that the subscription link is the problem.

The Switch Is On, but Some Destinations Fail

First check Global Routing: in Direct, selecting a server does not automatically route traffic through it; in Config, check the active file and the rules for the destination. Keep the server unchanged, temporarily switch to Proxy, and make a new request to the same destination. If Proxy works but Config does not, focus first on the configuration, policies, and name resolution settings. This narrows down the issue but does not prove that a specific rule is wrong.

If both modes fail while other destinations work, consider the destination's own status, specific connection conditions, and how the server handles that destination. Do not immediately reinstall the app or delete all configurations. Keep any working settings and retest the same destination one change at a time. For DNS, rule order, or additional protocol parameters, see the Complete User Guide; this page focuses on the initial connection steps.

Record the Results Before Making Another Change

A useful troubleshooting record includes the failure stage—import, connection, or actual access—the Global Routing mode, network type, exact message, the setting you just changed, and the before-and-after results. Redact subscription URLs, passwords, and personal account information. Do not share an entire configuration file in place of describing the issue; it may contain multiple sensitive connection details.

Once everything works again, restore your usual Global Routing mode, confirm that the intended configuration is selected, and repeat the actual access test from Step 4. Use the same verification cycle when you next update a subscription, adjust a configuration, or switch networks. If you just need a reminder of the steps, return to Add or Import or Test the Connection. For a deeper understanding of the settings, continue to the advanced guide.