Official Manual · iPhone and iPad

Shadowrocket Setup Guide:
Import a Subscription and Connect for the First Time

For your first connection, follow five steps: add your existing details on Home, choose Global Routing, authorize the VPN, and verify actual access. Get one connection working before adjusting rules, DNS, or On Demand so you can tell what effect each change has.

This page covers the steps for your first connection. For configuration file fields and complete rule syntax, see the configuration reference. To troubleshoot a specific issue, read the troubleshooting guide. The steps are the same on iPhone and iPad; the layout may vary by device.

Step 1: Add a Server or Import with Subscribe

First, identify what information you have. A subscription link retrieves a group of server entries and may be updated by the service that provided it. Individual server details include a protocol, address, port, and authentication fields. You don't need to add both; choose the method that matches the information you have. Make sure the original details are complete. A webpage address is not necessarily a subscription link, and a configuration file URL is not the same as a server subscription URL.

Have a Subscription Link? Select Subscribe

Open Shadowrocket, go to Home, and tap the add button to open Add Server. In the type list, select Subscribe, enter the complete subscription link in URL, give the subscription a name you can recognize, and save it. Return to Home and wait for the results. Check that server entries appear under the subscription group. If you see only the subscription name, wait for retrieval to finish before turning on the connection switch.

When copying a link, keep all parameters after the question mark. Don't add quotation marks, spaces, or line breaks. Some links contain personal access credentials; use them only on your own devices, and don't include the full link in public screenshots or support requests. If an error appears after saving, return to the edit screen and compare the URL with the original. Adding the same subscription again won't fix an incorrect address and can make it harder to choose the right entry later. To refresh subscription contents, update the existing subscription and check the results.

Have Server Details? Enter Them for the Specified Protocol

If you have details for an individual server, select the matching protocol in Add Server and enter the address, port, and corresponding authentication fields. For example, Shadowsocks, VMess, VLESS, and Trojan use different authentication details; don't choose a protocol based only on a similar-looking address. If the details include TLS or other transport parameters, check those fields too. Use the values from the original details rather than guessing.

Enter the hostname or address in the field specified for the server address, and put the port in the port field. Usernames, passwords, UUIDs, and TLS names each serve a different purpose and aren't interchangeable. If the details are provided as a QR code, use Scan QR Code to import them. After importing, open the entry to verify its type and key fields, then save it once everything is complete. QR codes, like subscription links, may contain credentials; don't share them publicly.

After adding a server, return to Home and select the entry you want to use from the SERVER list. Note the difference between an entry being saved and being selected: if the list contains multiple servers, make sure the one you want is selected before connecting. Remember its name and keep using the same server when you change Global Routing and verify the result in the next steps. This avoids changing multiple variables at once.

Step 2: Choose a Global Routing Mode

After adding and selecting a server, open Global Routing from Home. This determines how requests are handled overall; it doesn't fill in missing server details. Check this setting carefully during your first connection: even with correct server details, a different routing mode can produce unexpected results. This guide uses Config / Proxy / Direct for the three modes. Look for these English labels in the app.

If you only have a server subscription and haven't set up a rule configuration, try Proxy for a controlled test. This temporarily reduces the effect of rule selection, but doesn't mean every app or system request will be handled the same way. Choose a specific destination to test and check both actual access and the connection logs; don't assume a request went through the server based on the mode name alone.

Before using Config, open Config and confirm which configuration file is active. Config in Global Routing is a routing mode; the Config tab at the bottom is where you manage configuration files. They're related, but they're not the same action. Importing a server subscription doesn't switch your rule configuration. If traffic isn't routed as expected, check which file is active instead of adding the server again.

Rules are generally matched in order, and the matching rule's policy is applied. Keep this in mind when troubleshooting; you don't need to edit a complete set of rules before your first connection. For details on PROXY, DIRECT, REJECT, and FINAL, see the rules and configuration reference. After choosing a mode, return to Home and confirm the same server is still selected before moving on to the connection switch.

Step 3: Connect and Authorize the VPN

Check three things: Home shows an available server entry, that entry is selected, and Global Routing is set to the mode you chose. Then turn on the connection switch on Home. The first time you connect on this device, the system may ask for permission to add a VPN configuration. This creates a system network configuration; it is separate from using Subscribe to retrieve a server list.

Read the system prompt. Confirm it was triggered by your action in Shadowrocket, select Allow, and complete any device verification the system requests. Once authorization succeeds, return to the app and check that the switch and connection status remain on. If you previously dismissed the prompt, start the connection again and complete authorization. Tapping the switch repeatedly won't replace the system confirmation.

If the switch turns off soon after you turn it on, check for an error shown by the app or system. Then check whether the configuration was created successfully, another network configuration is taking over, or a device management policy is restricting the action. Don't delete all configurations before recording what happened. Close any other active connections normally, then test Shadowrocket on its own to reduce interference from changing network states.

A system VPN connection status only indicates that the network configuration is active. It doesn't by itself confirm successful authentication with the remote server or prove that every webpage is reachable. You still need to test a specific request. In Config, some destinations may use DIRECT according to the rules; that doesn't necessarily mean the connection switch failed.

While troubleshooting your first connection, use the manual switch and leave On Demand unchanged. On Demand can affect when a connection starts or resumes, and unfamiliar conditions can make a connection that reappears after being turned off look like a failure. First complete the stable test in the next step, then read the On Demand guide for your use case. To end the test, turn off the connection switch on Home and confirm the status changes.

Step 4: Verify with Connectivity Test and Actual Access

Once the connection is established, run Connectivity Test first. Note whether it returns a result and any error message, then open Safari and visit a page you know is available. These are two separate checks: the test reflects its method and target, while actual browsing also depends on destination DNS resolution, connectivity, TLS, and page resources. A test result doesn't mean every destination is reachable, and a single timeout doesn't prove that all requests will fail.

Set Up a Repeatable Comparison

Choose a specific page and note the network, server, and Global Routing mode. Wait for it to finish loading, then refresh it or open another page you know is available to see whether the result is repeatable. Don't update the subscription, switch servers, and change DNS at the same time; it will be hard to identify what caused a change. To compare Wi-Fi with cellular, record the results on the current network first, then switch only the network and test again.

If the same destination works in Proxy but not in Config, keep the server unchanged and check the active configuration and matching rules first. If actual access fails in both modes, continue checking the server details, remote availability, and local network instead of rewriting the entire rule set. Direct can provide a local access comparison, but success in Direct doesn't prove the proxy path works.

Check Results for Each Request, Not Just the Overall Status

To check which policy was applied to a destination, open the app's connection logs and look up the current request by domain or address. Review any visible policy, rule, or error details. Log locations and displayed fields may vary by version; refer to the interface you see. Make a clear new request before checking the corresponding log entry. It's easier to compare than guessing from a long history.

If you see DIRECT, first check whether it matches the active rules. If you see REJECT, check whether the expected blocking rule matched. If you see PROXY, then check the selected server and connection result. A webpage may request resources from several domains, so the main page loading doesn't always mean its images, sign-in, and other resources loaded too. For a partial failure, note the domain of the resource that failed instead of treating the entire site as unavailable.

After verification, set Global Routing to the mode you need for everyday use. If you use Config, keep the server and configuration file you verified, and change only one setting at a time. Your first connection is now complete. If something still isn't working, start with the troubleshooting steps below, beginning as close as possible to where the issue occurs.

Step 5: Troubleshoot Based on Where the Failure Occurs

Start by identifying the step that failed, then address the relevant setting. A subscription that retrieves no content, a connection switch that won't stay on, a timed-out test, and a webpage that loads only partially are four different issues. Calling all of them “can't connect” can lead you to change settings that are already correct. Work through the checks below, starting with your local network and narrowing down the cause. After each check, test the same destination again.

Subscription Import Failed or No Server Entries Appear

First, check that your device has network access. If the current connection makes it difficult to assess, turn off Shadowrocket normally and test basic access for comparison. Then check that the subscription link is complete, still valid, and returns data in a supported subscription format. Being able to open a webpage only confirms that the page is accessible; it doesn't mean the subscription URL returned valid data.

Make sure the link came from your own original details and doesn't include explanatory text accidentally copied with it. If the service changed the link, update the URL for the existing subscription instead of repeatedly refreshing the old one. After updating, check the actual entries in the group, then select a server. If retrieval failed, changing Global Routing later usually won't fix the import problem.

Server Added, but Authentication or Testing Fails

Open the selected entry and check the protocol, address, port, authentication fields, and TLS and transport settings against the original details. Pay particular attention to trailing spaces in passwords, complete UUIDs, and whether the TLS name is in the right field. Changing the display name won't change connection parameters, and renaming an entry won't fix an authentication error.

If your existing details include another entry known to work, switch to it for comparison while leaving all other settings unchanged. If multiple entries fail, check for local network changes and the status information provided with your original service. Don't turn off certificate verification just to pass a test. First check the device time, destination name, and original TLS settings.

Connected and Test Returns a Result, but Pages Won't Load

First, distinguish DNS resolution failures from connection timeouts and rule rejections. Check whether the DNS settings in the active configuration match what you intended to use, then use the connection logs to identify the specific domain. If one domain fails while other pages work, don't assume the whole connection is down. If multiple domains fail to resolve, check the DNS path and current network conditions first.

Don't add multiple DNS addresses from unknown sources at once. Record the current values, restore settings you know work, make a new request, and compare the result. If Proxy works but Config doesn't, check whether a rule sends the destination to DIRECT or REJECT, and whether FINAL provides the intended fallback. For detailed settings and issue categories, see DNS and connection troubleshooting.

Harder to Troubleshoot After a Change? Restore the Last Working State

Keep the original subscription details and a copy of any working configuration. Undo the most recent change, then repeat the test. A subscription update can change the server list, a configuration switch can change routing policies, and changing networks can affect DNS. Retracing changes in order is more useful for finding the cause than reinstalling the app. If you need to get the app again, follow the App Store purchase restoration guide; reinstalling isn't a general network troubleshooting step.

A complete first-connection check should confirm four things: the server details are saved and selected, the routing mode suits the test, the system connection is established, and the result for the destination can be explained. Once these checks are complete, add On Demand or more specific routing settings as needed. If something changes later, you can use the same sequence to troubleshoot.