Shadowrocket Setup Guide:
Import a Subscription and Connect for the First Time
Start with your existing connection details, then add them, choose a routing mode, connect, and verify access. This guide covers the steps for first-time use; see the configuration reference for rule fields and matching behavior.
If you’ve already completed a step, jump to the relevant section. When troubleshooting, note your current settings and change only one thing at a time.
STEP 01 / IMPORT
Add Server: Add a Server or Import a Subscription
After opening Shadowrocket, go to Home. Here you can view your server list, select a server, and control the connection. First, identify what information you have: a complete subscription link, or details for a single server, including its protocol, address, port, and authentication fields. Choose one method; you don’t need to complete both to get started.
Have a Subscription Link? Choose Subscribe
In Home, tap the add option in the top-right corner to open Add Server. Open Type and choose Subscribe. Paste the complete subscription link in the URL field, add a note to identify the entry, then save using the option in the top-right corner. Check the beginning and end of the link, including its query parameters, and make sure no spaces or line breaks were added when copying.
After saving, return to Home and wait for the subscription to load. Then check the subscription group and its server entries. Seeing the subscription name does not necessarily mean the server list loaded successfully; expand the group and confirm that it contains selectable entries. If the list is empty or an error appears, check the link and your internet connection before turning on the connection switch.
Updating a subscription fetches the list published by the service; it does not establish a connection. If your service provider changes server details, use the update option in the subscription’s action menu and check the refreshed entries. You may need to reselect a server if the list has changed, so confirm your selection after updating.
Have Server Details? Enter Them Under Type
If you have details for a single server, go to Add Server from Home and choose the protocol specified in your details under Type, such as Shadowsocks, VMess, VLESS, or Trojan—not Subscribe. Fill in the fields shown for that Type, including the server address, port, password, and any other authentication details. Required fields depend on the protocol and the information you have; don’t guess values based on an example for a different protocol.
A server address is not the same as a full web address. If your details specify a hostname, enter only that hostname. Put the port and authentication details in their respective fields. Follow your provider’s details for TLS, Server Name, and transport parameters; don’t disable security checks to compensate for incorrect settings. Save, then return to Home and check that the entry appears.
Have a QR Code? Use Scan QR Code
If your connection details are provided as a QR code, use Scan QR Code to read it and grant camera access if prompted. After scanning, check the imported Type, address, and required fields. A successful scan only means the QR code was read; it doesn’t confirm that the server can connect. Like a subscription link, a QR code may contain private authentication details, so don’t share it publicly.
Finally, select the server you want to use in Home and make sure the selection indicator is next to the correct entry. Your connection details are now ready. Next, choose how to route traffic before connecting.
STEP 02 / ROUTING
Global Routing: Choose How to Route Traffic
Return to Home and tap Global Routing to view the current selection. The three modes are Config, Proxy, and Direct. They determine how requests are routed; they don’t change the server address or authentication details, or fix an invalid subscription link.
Config: Use the Active Configuration
Config uses the active configuration to determine whether requests match PROXY, DIRECT, REJECT, or a specified policy group. Before choosing this mode, open Config at the bottom of the screen and check which configuration is active. A file appearing in the list does not mean it is active; look for the selection indicator or active status.
You don’t need to edit an entire set of rules before your first connection. If you have a trusted configuration that meets your needs, make sure it’s active, then return to Home and choose Config. A subscription updates server details; a configuration manages rules and other settings. Adding a subscription does not automatically configure traffic-routing rules.
Proxy: Test the Server Connection First
Proxy routes requests using the proxy mode, which can make it easier to test a first connection without rule-based routing affecting the result. If you have server details and want to check whether they work, temporarily choose Proxy, then test the connection and a web page. This doesn’t guarantee that every app or request will get the same result, or that the server is reachable.
If a destination works in Proxy but fails in Config, first check the active configuration, matched rule, and policy group instead of immediately deleting the server. After testing, choose a mode that suits your regular use; you don’t need to leave the troubleshooting mode selected.
Direct: Send Requests Without a Proxy Server
Direct sends requests without a proxy server. Use it to check whether your regular internet connection works or when a request needs a direct connection. With Direct selected, an enabled connection switch does not mean requests are going through the selected proxy server. Consider Global Routing and the switch status together when interpreting the result.
After choosing a mode, return to Home and confirm the selected server once more. Next, start the connection and complete the system authorization prompt if this is your first time connecting.
STEP 03 / CONNECT
Home: Connect and Complete First-Time Authorization
In Home, confirm that the right server is selected and Global Routing is set for your test. Then turn on the connection switch at the top. The first time you connect, the system may ask to let Shadowrocket add a VPN configuration. Check the app name in the prompt, tap Allow, and authenticate with your device passcode or biometric authentication as prompted.
This prompt allows the app to create a system network connection configuration. It is not a subscription login, and you don’t need to enter your server password in the prompt. After authenticating, return to Shadowrocket and check the switch and connection status. If authorization interrupted the process, you may need to turn the switch on again. Don’t assume the connection is established just because the system prompt disappeared.
If you previously declined authorization, turn on the connection switch again and follow the system prompt. If the device is managed by an organization, has configuration restrictions, or the system says the relevant settings can’t be changed, check the device management requirements instead of repeatedly deleting existing system configurations. Authorization issues and server authentication failures occur at different stages and should be handled separately.
For your first test, leave On Demand turned off so you can clearly observe the results of connecting and disconnecting manually. On Demand starts a connection when specified conditions are met; it does not improve connection quality. Once manual connection, routing, and access to your target are confirmed, review its conditions if needed.
A VPN status indicator in the system or an enabled connection status in the app only confirms that the connection has been established. It does not guarantee that the remote server, DNS, or destination website is working. Don’t stop here: test an actual request next, distinguishing an enabled switch from successful access to your destination.
When you’re finished, return to Home and turn off the connection manually, then check whether the system status changes. If it reconnects automatically, check whether On Demand is enabled and review its conditions before assuming the switch has failed. For details on on-demand connections, see the FAQ about On Demand.
STEP 04 / VERIFY
Connectivity Test: Verify the Connection and Routing
Start by checking your regular internet connection. If your current Wi-Fi requires sign-in through a browser, complete that first; on mobile data, confirm the data connection works. Switching servers repeatedly is unlikely to help if your basic connection is unavailable. Keep a page you know you can access as a reference for checking your internet connection.
Test the Selected Server, Then Make a Real Request
Return to Home and use Connectivity Test to check the server connection. Make sure the selected server is included in the test. The result can help determine whether the server is reachable, but it depends on the test destination, your current network, and the server’s status. A successful test doesn’t mean every website or app will work, and a timeout alone doesn’t prove that a subscription has expired.
Next, open a browser and visit a destination you know is accessible. To avoid mistaking a cached page for a successful new request, refresh the page or reopen the address and check that you can navigate to other pages. Testing an app you actually use is more informative than checking connection status alone.
Check Matched Policies in Config
If you’re using Config, check the request in Logs and review the destination domain, matched rule, and final policy. A request matching DIRECT isn’t necessarily an error; it may be the expected result of your rules. Likewise, PROXY only indicates that the proxy policy was selected; check whether the request succeeded as well.
If a request that should use the proxy goes direct, first check that the right configuration is active, whether an earlier rule matched, and whether the policy group has the intended member selected. Rules are usually matched in order, and changing one may affect subsequent requests. When you’re getting started, focus on confirming the result; avoid changing several rules in response to a single issue.
You can run a controlled comparison: use the same network, server, and destination to repeat the request in Proxy and Config. If it fails only in Config, focus on the rules and configuration. If it fails in both, check the server details, internet connection, and server status. Change only one condition at a time so you can interpret the results.
STEP 05 / DIAGNOSE
Common Issues: Check Each Stage in Turn
If a test above fails, note which step failed and check the following items in order. A subscription that won’t load, a server that won’t connect, and a website that won’t open involve different parts of the setup. Treating them all as “Shadowrocket won’t connect” makes troubleshooting too broad and can lead you to change settings that are already correct.
Subscription Not Imported: Check the URL and Fetch Result
Return to the relevant Subscribe entry and check that the URL is complete, doesn’t include extra explanatory text, and is still valid according to your service provider. An account page that opens in a browser isn’t necessarily a subscription URL that can be imported directly. If you’re unsure about the link type or whether it’s valid, confirm with your service provider. Don’t try to fix it by randomly editing query parameters.
If the subscription updated successfully before but now fails, first check that your current network can reach the service required to access the subscription URL, then try updating once more. Check whether the error indicates a network timeout, authentication failure, or content parsing issue to help distinguish a network problem from a link problem. Don’t delete a working entry until you’ve confirmed the replacement link is valid.
Entry Listed but Won’t Connect: Check the Server Details
First confirm that you selected an actual server entry, not an empty group or the wrong item. Then check the Type, server address, port, authentication details, and required transport parameters. When entering details manually, check capitalization in passwords, the port, and Server Name carefully. If the details came from a subscription, check that it updated successfully and that the service is active before editing the entry; a later update may overwrite manual changes.
If Connectivity Test times out, try one other network for comparison if available, keeping the server and test destination the same. Note any difference in the results. If the test fails on multiple networks, check the server status. An enabled connection switch alone does not rule out a server-side connection failure.
Only Some Requests Fail: Check Routing, DNS, and Logs
First check that Global Routing hasn’t been set to Direct by mistake, then confirm that the expected file is active on the Config page. For an issue with a specific destination, find the request in Logs and check whether it matched REJECT, an unexpected DIRECT, or a different policy group. Don’t mask a specific configuration problem by routing all requests through Proxy indefinitely.
If the logs indicate a domain resolution failure, check DNS separately: confirm that your internet connection works, review any changes to DNS settings in the active configuration, and check whether the same domain resolves consistently. DNS settings are interdependent, so this first-connection guide isn’t the place to fill in values one by one. For changes, see the Configuration Fields and Rules Reference; understand the active configuration before changing one setting.
Connection Status Keeps Changing: Check System Conditions
Check whether you’ve just switched from Wi-Fi to mobile data, whether network sign-in is still required, and whether On Demand is triggering a reconnect. If the connection returns immediately after you turn it off manually, pause the on-demand conditions and observe what happens. If the device shows an authorization or management restriction, check the system prompt for details instead of treating it as an expired subscription.
If you still can’t identify the cause, note the current Global Routing mode, the selected server’s protocol, the failed destination, the exact error, and which step failed. Then see Frequently Asked Questions and Troubleshooting. Hide private information such as subscription URLs, passwords, authentication details, and QR codes; the error category and relevant context are enough.