Official Guide · First Connection
Shadowrocket Subscription Import and Connection Guide
Follow this sequence: import your connection details → choose Global Routing → connect → verify the result → troubleshoot. Test one existing server entry first, then organize other subscriptions and rules. Avoid changing several settings at once during initial setup.
- App screens Home / Config
- Devices iPhone / iPad
- Before you begin Connection details ready
This page covers the steps for getting started. For subscription updates, managing multiple subscriptions, field explanations, and backups, continue to the Subscription and Server Management Guide.
[Before You Start]Before you begin, install Shadowrocket from the App Store and make sure you have your own subscription URL or server details. This site does not provide, sell, or recommend servers or subscriptions. A one-time app purchase is not a service plan; buying the app does not automatically provide a server you can use.
If you haven’t installed the app yet, read How to Buy and Install Shadowrocket from the App Store first. For iPhone and iPad system requirements, compatibility, and purchase eligibility, refer to the App Store listing. The steps below use the English labels shown in the app and don’t rely on fixed button positions.
[Subscribe]Step 01 · Prepare a connection entry
Add a Server or Import an Existing Subscription
First, identify what you have: a subscription URL, a single share link, or individual server details. Each uses a different option. Don’t choose Subscribe just because a link looks like a web address.
Have a subscription URL? Choose Subscribe
Open Shadowrocket, go to Home, and tap the plus sign in the upper-right corner to open Add Server. Under Type, choose Subscribe. Enter your complete subscription URL in URL, add a note to identify it, and save. A subscription usually returns a list of server entries. After saving or updating, return to Home and check that the group and entries appear. Don’t assume the import is complete just because you’re still on the edit screen.
Check the address from its first character to its last when copying it. Query parameters may contain credentials, so don’t remove anything after the question mark. Avoid copying chat text, curly quotation marks, line breaks, or trailing punctuation along with the URL. The example below is only to illustrate a subscription URL’s structure and cannot be used to connect. Use your own complete URL.
https://example.com/sub?token=xxxxIf no servers appear after saving, first check that the URL is complete, then review the message returned by the app. Don’t repeatedly add the same subscription to make a list appear, or change Subscribe to a single-server protocol to try to parse it. An empty list and a failed connection to one server happen at different stages and need separate troubleshooting.
Have individual server details? Enter them in Add Server
If you have an address, port, password, and protocol details, choose the matching protocol under Type in Add Server, then fill in the relevant fields shown. Address should be the server’s hostname or address; don’t add a webpage path. Enter the Port exactly as provided. Whether you need fields such as password, encryption method, UUID, TLS, or SNI depends on the selected protocol and server requirements. Don’t guess by copying values from another entry.
Save when you’re done, then return to Home and check that the new entry appears. The same protocol doesn’t mean the same settings: a Trojan password and SNI can’t be substituted for each other, nor can a Shadowsocks encryption method and password. If required details are missing, check your existing server information instead of disabling verification to bypass a prompt.
Have a share link or QR code? Check the imported entry
Content starting with ss://, vmess://, vless://, or trojan:// is usually a single share link, not a subscription that can be updated over time. To import from the clipboard, follow the prompt shown by the app. If you have a QR code, scan it with Scan QR Code and allow camera access when prompted. Don’t post a QR code publicly to ask someone else to identify it.
Whichever method you use, return to Home, tap the server entry you want to use, and check the selection indicator. Select one entry before continuing; a subscription group may contain multiple entries, but that doesn’t mean they’ll all be used at once. For more on importing and organizing entries, see the Subscribe Management Guide.
[Global Routing]Step 02 · Choose how traffic is handled
Choose Config, Proxy, or Direct
After adding a server entry, choose how to use it. Global Routing and server selection are separate: Global Routing determines how traffic is handled, while server selection determines which server entry to use when a proxy is needed.
In Home, open Global Routing and choose one of three modes for your current needs: Config, Proxy, or Direct. Return to Home, check the displayed mode, and then turn on the connection switch. Don’t rely on remembering a previous selection; check the current mode again when troubleshooting.
Config: Apply the active configuration file
Choose Config when you have a rules configuration and want different destinations to use different policies. Then open Config and confirm that the configuration file you intend to use is active. Seeing a file name in Config or importing a file into the list doesn’t confirm that it’s active. Subscriptions provide server entries; configuration files organize rules. Importing a subscription doesn’t mean your rules are ready.
In Config mode, a destination may use PROXY, DIRECT, or another specified policy, depending on the rules. Rule order and the final fallback rule also affect the result. If a website connects directly, don’t immediately assume the server is unavailable; first check which policy the destination is expected to match. To get started, just confirm the active configuration—you don’t need to edit all the rules.
Proxy: Check the selected proxy route
To check whether the selected server can handle typical traffic, you can temporarily choose Proxy. This reduces variables from rule matching, but system network behavior and related settings can still affect the result. It doesn’t guarantee that every connection on your device will use the proxy. After testing, switch back to Config if you normally use rule-based routing, then check that your destination works as expected.
Direct: Bypass the selected proxy server
Direct connects without using the selected proxy server, so it can’t confirm that the proxy works. If a server is selected in Home but Global Routing is set to Direct, your traffic may not pass through that server at all. To compare your regular network with the proxy route, note the results before and after switching. Change only the mode each time, so changing servers doesn’t make the results hard to compare.
You’ve completed this step when you can identify the selected mode and explain why you chose it. For details on matching DOMAIN-SUFFIX, IP-CIDR, and FINAL rules, continue to the Server and Configuration Guide. For now, keep the settings you’ve already confirmed.
[Connect]Step 03 · Establish the system connection
Turn on the switch and allow the VPN configuration
Return to Home, check the selected server and Global Routing mode again, then turn on the connection switch at the top. This first authorization only allows the app to add a VPN configuration on your device; connections use your own existing subscription or server details.
The first time you connect, the system may ask Shadowrocket to add a VPN configuration. Confirm that the prompt matches the action you’re taking, then follow the system instructions and complete any required device verification. This allows the app to establish the corresponding network configuration on your device. It doesn’t mean the system has checked your server password or confirmed that the remote service is reachable.
If you dismissed the prompt earlier, return to Home, try turning on the switch again, and watch for the authorization screen. Don’t delete device configurations you don’t recognize just to continue. If your device is managed by an organization, check whether its management policies allow this action. Repeatedly changing server details won’t resolve a system restriction.
After confirming with the system, return to Shadowrocket and check whether the connection switch stays on. Wait for the current operation to finish instead of toggling the switch repeatedly. If it turns off immediately, note the exact error message, then use Step 05 to distinguish between authorization, network, and configuration issues. The exact message is more useful for troubleshooting than a general description like “it won’t open.”
Follow the same checks on iPhone and iPad. Lists and details may appear in different places depending on screen size, so look for labels such as Home, Global Routing, and Config rather than relying on fixed coordinates. Don’t judge a connection as failed solely because the VPN label isn’t shown in a particular place in the status bar.
For now, don’t enable additional automatic connection behavior or change On Demand at the same time. First confirm that connecting and disconnecting manually work as expected, then consider automation. After turning off the connection switch in Home, check the app’s status again, especially on devices where On Demand was previously configured. This helps distinguish an automatic reconnection from a switch that won’t stay off.
[Checkpoint]A switch that stays on only means the local connection has advanced to the next stage. Test the server and verify that your traffic follows the intended policy in the next step.
[Connectivity Test]Step 04 · Check the results
Test first, then verify access
Check the local switch, server test, and actual access separately. No single result proves that the entire setup is correct.
In Home, run Connectivity Test for an existing server entry and check the result for the server you plan to use. The test indicates reachability and response under current network conditions; it isn’t a service quality guarantee and can’t replace checking a login, webpage load, or other real-world use. Don’t choose and switch servers repeatedly based on a single test result.
Next, open a browser or the app you need and visit a service you’re authorized to use. Choose a page with an easy-to-check result and confirm that its content actually loads, rather than just displaying a previously cached title. If the destination requires a login, separate account access issues from network issues: a login denial doesn’t necessarily mean the proxy connection failed.
With Config selected, check whether the active configuration routes the destination as expected. If needed, use available connection logs to confirm which policy was applied. Log displays vary by app version; there’s no need to look for a particular color or icon. If the destination matched DIRECT, a page loading successfully doesn’t prove that the selected proxy server carried that request.
If access works in Proxy but not in Config, check the active file and rules in Config before reimporting your subscription. If Connectivity Test succeeds but a destination still fails, check the service itself, protocol-specific fields, DNS, and other factors. These results aren’t contradictory: the test and the actual request may use different destinations and processes.
When you’re done, make a brief note of your network type, selected server, Global Routing mode, Connectivity Test result, and what happened when you tried to access the destination. Use names you can recognize; don’t include passwords or complete subscription URLs. Then disconnect manually and check that your regular network behaves as expected again. This gives you a clear before-and-after comparison.
Your first connection test is complete when the selected server, routing mode, and access result make sense together. Repeat these checks when you change a subscription, server, or configuration file; there’s no need to change every setting again.
[Diagnostics]Step 05 · Narrow down the issue by stage
Common Issues and Troubleshooting Steps
Identify the stage where the problem occurs, then change the relevant setting. Change one thing at a time and test the same destination again after each change, so you can compare results.
Subscription saved, but no entries appear or parsing fails
Return to the subscription editor and check the URL. Make sure it isn’t a provider’s login or information page, or a single share link. Check that no query parameters were left out when copying and that the URL hasn’t been replaced or expired. If the app displays a message about the returned content, keep the message and check the status of your existing subscription. Don’t post the URL publicly for others to test; its token may grant access.
An update failure doesn’t mean you need to delete the existing group. First check whether the original entries are still there, then determine whether the update request failed or the content actually changed. Avoid repeatedly deleting and re-adding entries without a backup, or you could lose both the original details and your changes.
Server entry appears, but the test fails
Turn off the connection first and check that Wi-Fi or cellular can access the internet normally. If the network requires a sign-in page, complete that step first. Then open Add Server and compare the protocol, address, port, and authentication fields with your original details. When entering values manually, watch for trailing spaces, capitalization, and easily confused characters. Don’t rely on the entry’s note to verify its settings.
If the protocol requires TLS or SNI, check those settings against your existing server details. The server address and the name used for verification may serve different purposes, so don’t change them to match just because they differ. Don’t disable certificate verification to hide the problem. Check the settings, device time, and server status first.
Connection switch won’t stay on
Check whether you allowed the system VPN configuration and whether the app shows a specific error. Confirm that a server is selected, and check whether another network configuration is affecting the connection. Stop any known conflicting connection before trying again. Don’t delete device settings if you’re unsure what they do, and don’t treat buying the app again as a troubleshooting step.
Only some destinations fail after connecting
Check Global Routing first. With Direct selected, traffic isn’t using the intended proxy route. With Config selected, check whether the destination matches a different policy, then try Proxy for a controlled comparison. If only one app fails while a browser works, check the app’s account status, cache, and the destination service. That alone doesn’t mean the entire subscription is unusable.
For further analysis of DNS, rule order, and protocol fields, see the Subscription and Server Management Guide. At this stage, avoid changing DNS, rules, server details, and automatic connection settings all at once. Otherwise, even if access is restored, it will be hard to tell which change fixed the issue.
Review the results before making more changes
After troubleshooting, identify whether the issue was with importing, routing, system authorization, or destination access. If you need to verify details with your service provider, share only the time of the failure, network type, protocol, and a redacted error message. Remove complete subscription URLs, passwords, UUIDs, share links, and QR codes. Check screenshots for personal information too.
To start again, return to Step 01: Check the import. If the server entry is already saved correctly, continue with choosing Global Routing. Checking each step’s result makes it easier to find the real issue than rebuilding the entire setup.