Shadowrocket First Connection Guide

Step 1: Add a Server or Import a Subscription

First, make sure a server is available to select in Home. Then configure the routing mode and connection. A subscription link and details for a single server are two different types of input: a subscription retrieves a set of server entries that can be updated, while individual server details save the parameters for one server. Choose the method that matches the information you have; there’s no need to add the same details twice.

Have a subscription link? Choose Subscribe

Open Shadowrocket and go to Home. Tap the plus sign in the top-right corner, then open Add Server. Under Type, choose Subscribe and enter your complete subscription link in URL. Add a name to help identify it, then tap Done in the top-right corner. Return to Home and wait for the subscription to load. Check the relevant group for server entries.

Copy the entire link from its original source. Don’t include surrounding text, spaces, or line breaks, and don’t remove parameters from the end of the link just because they look unusual. A subscription URL may contain credentials required for access. Use it only on your own device; don’t post the full link in public comments, group chats, or troubleshooting screenshots.

If you see the subscription name but no servers after saving, first check whether your current network can retrieve its contents, then try updating the subscription. A service provider’s website address is not necessarily a subscription URL: login pages, order pages, and general information pages are not valid Subscribe inputs. If the result is a web page or an error, ask your service provider what the link is for instead of repeatedly changing protocol settings.

Have details for one server? Enter them in Add Server

If you have separate server details such as an address, port, password, or UUID, tap the plus sign in Home to open Add Server. Under Type, choose the protocol specified in your details, such as Shadowsocks, VMess, VLESS, or Trojan—not Subscribe. Enter the server address, port, and authentication details as provided. The fields vary by protocol, so don’t fill in fields based on a different protocol.

Pay particular attention to encryption, TLS, Server Name, transport, and path settings. These aren’t optional notes; they must match the server’s requirements. A correct address and port don’t guarantee that the entire entry is configured correctly. Don’t switch protocols or turn off TLS just to clear a warning. If required details are missing, check your service provider’s information first.

If you have a compatible QR code, use Scan QR Code to read it. Camera access is used only for scanning. After scanning, check the detected protocol, address, and port before saving. QR codes may contain connection credentials, so don’t share them publicly. Scanning and manual entry are simply different ways to add details; the steps for selecting a server and connecting are the same.

Return to Home and select a default server

After saving, select the server you want to use from the list in Home and make sure the selection dot on its left is highlighted. Seeing server names means the import returned entries; it doesn’t mean every server has been tested or that one has been selected as the default. For your first setup, choose a clearly named server that suits your needs. Avoid changing other settings while switching servers.

You’re ready to continue when a server appears in Home, the desired entry is selected, and you can open it to check its details. Subscribe manages the source of server entries; Config manages configuration files. They are separate features. For an overview of these terms, see the quick reference. Once the import is complete, continue to the next step.

Step 2: Choose Global Routing

The server determines the endpoint used for proxy connections; Global Routing determines how traffic is handled. In Home, tap Global Routing and choose Config, Proxy, or Direct for your current needs. For your first test, be clear about which mode you selected. Otherwise, even with the connection switch on, normal routing behavior may be mistaken for a connection failure.

Config: Use the Current Configuration

Config handles connections according to the active configuration file and its rules. Before using this mode, open Config and confirm that the selected file is the one you intend to use. A file appearing in the list doesn’t mean it’s selected, and its name alone doesn’t tell you what rules it contains. If you don’t have a configuration ready, complete a basic connection test first. It’s easier to troubleshoot than importing multiple configurations from unknown sources at once.

Rules are usually matched in order, and a destination may be assigned DIRECT, PROXY, or another configured policy. For example, DOMAIN-SUFFIX,example.com,PROXY sends matching domains through PROXY. FINAL,PROXY sets the handling policy for connections that don’t match any earlier rule. This explains the syntax; you don’t need to edit rules during initial setup or overwrite an existing configuration based on this example.

Proxy: Check the Proxy Route

Proxy sets the overall routing mode to use the proxy. It’s useful for checking whether the selected server can handle actual requests. After selecting a server in Home, choose Proxy, then turn on the connection in the next step. This can reduce interference from routing rules during an initial test, but it doesn’t guarantee that every request will always go through a remote server. System traffic, exclusions, and other settings may still affect the route.

If Connectivity Test and web access work in Proxy but a specific destination fails in Config, check the rule or policy that matches that destination first. You don’t need to reimport the entire subscription. This comparison helps distinguish an unavailable server from unexpected routing behavior.

Direct: Not a Proxy Success Test

Direct handles traffic without using the selected proxy server as the usual route. It can help you compare against the device’s existing network, but opening a website in Direct doesn’t prove that the server you just added works. Likewise, turning on the app’s connection switch and using a proxy are two separate things; the switch status alone doesn’t prove proxy access.

When you finish this step, note the selected routing mode and, if using Config, the active configuration file. Keep both unchanged during follow-up tests where possible. For a detailed explanation of rule priority, policies, and configuration fields, see the full manual. For now, make sure your test matches the selected mode.

Step 3: Turn On the Connection and Allow the VPN Configuration

Return to Home and check the default server selection and Global Routing once more. If everything looks right, turn on the connection switch at the top of the screen. The first time you connect, the system may ask to let Shadowrocket add a VPN configuration. This authorization lets the app handle network traffic through the system; it doesn’t mean your subscription has been verified.

In the system prompt, confirm that Shadowrocket is the requesting app, then tap Allow and complete any identity verification requested by your device. Don’t switch apps repeatedly or tap the connection switch over and over during authorization. When the process is complete, return to Home and wait for the connection status to update. If you previously canceled, start the connection again and follow the system prompts.

System prompts, authentication methods, and status indicators may look different on iPhone and iPad. Follow what appears on your device. To check the system configuration, look for VPN-related items in Settings and confirm that a Shadowrocket configuration is present. Don’t delete device management configurations you don’t recognize just to fix a connection issue.

Also check whether another VPN connection is active on your device. Competing configurations can cause a connection to drop immediately, a switch to turn itself off, or a status that doesn’t match what you expect. Identify which configuration is enabled before testing. If a managed device restricts adding VPN configurations, follow its management requirements; changing server settings won’t remove a system restriction.

This step is complete when the system connection is established—not when every destination is accessible. A normal connection status means local network handling has started; you still need to check connectivity to the remote server and try an actual website. If the switch won’t stay on, troubleshoot authorization and system status before changing DNS or rules.

Step 4: Run Connectivity Test and Check Actual Access

Once connected, find Connectivity Test in Home, run it, and wait for the result. The test shows connectivity under current conditions. Note whether it succeeds, times out, or returns another error instead of recording only the latency. A latency test in the server list and actual access after connecting are different checks: a server response doesn’t confirm that authentication, transport, and destination access are all working.

Test connectivity, then open a website

After the test, open a browser and visit a website you need to use. Start with one known, clearly defined destination; don’t open a large number of pages at once. If the page was already open, refresh it and confirm that its contents reload. Cached content doesn’t prove the current route is working. Test one destination at a time so you can match the browser result to the app’s records.

If Connectivity Test succeeds but a website won’t open, the test and website may have different access requirements, or the issue may involve DNS, rule matching, or the destination itself. Conversely, a temporary failure to reach the test destination doesn’t mean every server has failed. Consider the test result together with actual access; don’t rely on a single result as a complete diagnosis.

Using Config? Check the routing rules

If you’re using Config, test at least one destination expected to connect directly and one expected to use the proxy. In the app’s connection records, check the relevant requests and their policy results against the rule order in the active configuration. A website opening only proves that this particular request succeeded; to confirm it followed the expected route, check the matching record.

Data can help show traffic changes during a connection, but increasing traffic doesn’t mean the rules are correct or confirm the route used by every app. For your initial check, focus on these points: the selected server is clear, Global Routing is set, Connectivity Test returns a result, and the destination is accessible. If using Config, you should also be able to explain which policy handled the request.

If all four checks match your expectations, keep the current settings and start using Shadowrocket. There’s no need to keep switching servers for a lower test result or change DNS right away. Note the setup that worked so you can compare the network, routing mode, and server if an issue comes up later.

Step 5: Troubleshoot by Failure Stage

First identify whether the problem is missing imported content, a system connection that won’t establish, or access problems after connecting. Each stage calls for different checks. Change one thing at a time and retest the same destination. If you change the server, DNS, and configuration all at once, you won’t know what fixed the problem—and it may be harder to troubleshoot next time.

Subscription has no entries: Check the URL and update

Return to the Subscribe entry and check that the URL is complete, isn’t a service provider’s website, and can be reached from your current network. Check whether your provider has reset, expired, or replaced the link. If an update fails, keep any existing working entries, review the error, and then decide whether to import again. Creating the same subscription repeatedly usually won’t fix an access issue with the original link.

If a new subscription returns a different server list than expected, first check its source and whether the service is active. Don’t share the full URL publicly when asking for help. Describe what happened—for example, “the list is empty after updating” or “authentication failed”—and ask your service provider to check your account and subscription status.

Connection switch won’t stay on: Check system authorization

If the switch turns itself off immediately, check whether you canceled the system prompt to add a VPN configuration and whether your device allows the configuration to connect. Return to Home, start the connection again, and check whether the system prompt is hidden or still waiting for confirmation. The system connection hasn’t been established yet, so switching servers in your subscription usually isn’t the right first step.

If the status looks wrong, also check which VPN configuration is enabled and whether your device has management restrictions. A working regular network rules out only some basic network issues; it doesn’t replace the system authorization Shadowrocket needs.

Connected but Connectivity Test fails: Check the server and network

First, check that the server selected in Home is the one you just entered or intended to test. Then verify its address, port, password or UUID, TLS, and transport settings. It’s easy to select the wrong server when names are similar. If your subscription includes another entry you know works, keep the other settings unchanged and switch only to that entry for comparison. There’s no need to reimport everything.

Next, confirm that the device’s current network works. If appropriate, retest on another network you’re allowed to use. Use the same server and destination after switching networks so you can compare results. A failed test may also be caused by the server-side service; the app’s connection switch can’t confirm that your provider’s authentication and service are still active.

Only some destinations fail: Check rules and DNS

If Proxy works but Config doesn’t, return to Config and check the active file and the policy matching the destination. Look for an earlier DIRECT or REJECT rule; don’t check only the last rule. Save the original configuration before editing, change one rule at a time, and retest to confirm that the destination is handled differently.

If the error points to domain resolution, check your current DNS settings instead of assuming DNS is the cause of every failure. Record the original value before making changes and use settings you understand and have a clear reason to choose. Replacing multiple DNS addresses just because a website won’t load adds more variables. Review DNS, IP-CIDR, and FINAL in the quick reference, then consult the full manual for more detail.

Still not working? Prepare a concise troubleshooting report

Before contacting your service provider, note the protocol, Global Routing mode, the step where the failure occurred, the Connectivity Test result, and whether the same issue occurs on another network. You can include error text with sensitive details removed, but never share your full subscription link, password, UUID, QR code, or identity details. A specific error description is more useful than simply saying “it won’t connect.”

After the initial setup, keep everyday use simple: update your existing subscription when needed, check the default server and active configuration, then connect and verify access. The App Store handles app downloads and updates, Subscribe updates your existing server list, and Config manages configuration files. Each has a separate role; a temporary server issue doesn’t mean you need to buy the app again.