1. Add a Server or Import a Subscription

First, identify what kind of information you have and choose the matching option. A subscription URL typically retrieves and updates a list of server details. A server share link describes a single connection, while separate fields such as address, port, and password must be entered manually. Similar-looking URLs can serve different purposes: an account page, an information page, and a subscription URL are not interchangeable.

Existing Subscription: Use Subscribe

Open Shadowrocket, go to the Config page, and find Subscribe. Enter your existing subscription URL in the subscription prompt and follow the on-screen instructions to import it. Copy the entire URL, including any query parameters after the question mark. Check that there are no extra spaces, line breaks, or punctuation at either end. URLs may contain sensitive access credentials; don’t post them publicly or share the full link when asking for help.

After submitting the URL, check for an error message, then return to Home and look in the SERVER section. The import is complete when selectable servers appear in the list; closing the input window alone does not confirm success. If your subscription supports updates, refreshing it retrieves the latest remote content. Server names, counts, and settings may change, so check the results after each update, especially for entries you edited manually.

A subscription URL and a full configuration file URL are not the same. A subscription URL is primarily used to manage server details; a configuration file may also contain rules, domain mappings, and other settings. If an import adds a configuration but no servers appear, check what type of information the URL provides. Don’t keep pasting the same URL into different sections.

Existing Server Details: Use Add Server

Return to Home, tap the plus button, and open Add Server. Choose the protocol that matches your existing details, then enter the server address, port, and authentication information. The available fields change depending on the protocol. Two protocols may both use a password or UUID, but that doesn’t make their configurations interchangeable.

For example, check the encryption method and password for Shadowsocks; enter the UUID and corresponding fields for VMess or VLESS; and check both the password and TLS settings for Trojan. Match any additional settings, such as transport, TLS, server name, and path, to your existing details. Don’t guess at fields you weren’t given, and don’t disable certificate verification as a general fix. Save the entry, then return to SERVER and select it.

Existing Share Link or QR Code

For a server share link, use the app’s clipboard import option. For a QR code, select Scan QR Code and allow camera access when prompted. After scanning or importing, check the protocol, address, and port. Successful import only means the app recognized the content; it does not confirm that the remote service works. QR codes may contain passwords or other credentials, so protect them like the original link.

At this stage, confirm that a specific server appears in Home and that the one you want to use is selected. Next, choose how traffic should be handled. For more on import options and formats, see Subscription Import Options. For field definitions, see the Glossary.

2. Choose Global Routing

Tap Global Routing on Home. This setting determines how traffic is handled; it’s separate from choosing a server in the previous step. Selecting a server doesn’t mean every connection will use it. Likewise, choosing a proxy mode won’t fix incorrect server details.

Config: Follow the Active Rules

Config is intended for everyday use with an existing rules configuration. The app uses the rules in the active configuration to decide how to route connections, applying policies such as PROXY, DIRECT, or REJECT. As a result, different domains may be handled differently in the same session, as intended by the rules. Before selecting this mode, check which configuration is active in Config—not just whether a file appears in the list.

You don’t need to write rules as part of the initial setup. If you’re not sure where the current configuration came from or what it contains, first check that your server works, then decide whether to use that configuration. Rule order, fallback policies, and syntax are covered in the Rules and Configuration Reference; there’s no need to change them during your first connection.

Proxy: Isolate Rule-Related Issues

Proxy can help with an initial test or troubleshooting: connections normally handled by the app are sent through the proxy, which helps distinguish a server connection problem from a rule that changes the route. It doesn’t replace a server quality test or guarantee access to every destination. System-level traffic exceptions and the app’s own connection behavior may still affect the result.

Direct: Connect Without the Proxy

Direct connects to the destination without routing traffic through the selected proxy server. If you’re checking whether the server works, a page loading in this mode doesn’t prove the proxy connection is working. Selecting this mode also doesn’t turn off the connection switch on Home; routing mode and system connection status are separate settings.

For the initial setup, select Proxy and use the same server for the next verification steps. Once it works, switch to Config to check how your everyday rules behave. After each switch, start a new request so an existing browser connection doesn’t affect the result.

3. Turn On the Connection and Approve It

Return to Home. Check the selected item under SERVER and the current Global Routing mode, then turn on the connection. Before connecting, you may see a status such as Not Connected. After turning it on, check whether the status changes and whether it immediately disconnects again. Don’t toggle the switch repeatedly while a system prompt is still open.

The first time you connect, iOS may ask to let Shadowrocket add a VPN configuration. This allows the app to create a system network configuration; it does not ask you to buy the app again or fill in server details. Confirm that the prompt was triggered by Shadowrocket, then approve it and complete any device passcode or authentication step required by iOS. Complete verification in the system interface; never enter your device passcode in a server form or on a webpage.

If you dismissed the prompt, return to the app and try connecting again, then follow the prompt that appears. You can also search for VPN in system Settings to check Shadowrocket’s configuration status. Before changing anything, check whether the device is managed by an organization and subject to restrictions. If you find a management restriction, follow your organization’s device policies rather than repeatedly deleting unfamiliar system configurations.

After approval, return to Home and check the connection status. A system VPN connection means local network traffic handling has started; it doesn’t confirm that the remote server, DNS, and destination websites are all working. Verify access with a real request next. If the switch turns off immediately, note the system prompt and any app error before considering a reinstall.

During the initial test, leave the existing On Demand settings unchanged so automatic connection conditions don’t complicate troubleshooting. If the connection starts again automatically after you turn it off, check whether On Demand is enabled and review its triggers. Once manual connection is working reliably, adjust automatic connection behavior to suit your needs.

4. Verify That the Connection Works

Verification has three parts: whether the server passes a test, whether the system connection stays active, and whether requests to your destination work as expected. These results are related, but none can stand in for the others. Record each one separately to make troubleshooting more effective than simply reporting that it won’t connect.

Start with Connectivity Test

Run Connectivity Test from Home and check the result for the current server. The test method and destination affect the outcome, so a successful test doesn’t mean every website will work, and a single timeout doesn’t prove that all connections are unavailable. If the list contains several servers, check which one was tested and which one is selected.

Don’t draw conclusions from the test number alone. The test request may use a different route or destination from your actual traffic. If tests keep failing, check the server details, current network, and remote service status. Don’t change DNS, TLS, protocol, and routing mode all at once to improve one test result; you won’t be able to tell which change made a difference.

Make a New Request

Keep the connection on, open your browser, and revisit a known HTTPS page that normally responds. Refreshing an old tab may show cached content, so start a new request and check that the page actually loads. Test a few different destinations for comparison; don’t judge the entire connection by one website’s failure.

If the browser works but an app doesn’t, check whether the app is holding on to an old connection or has its own login, permission, or service issue. Reopen the app and test again. Don’t blame Shadowrocket for an account error, scheduled maintenance, or a website’s own error without first checking the cause.

Check How the Rules Handle Traffic

After verifying Proxy, switch to Config and revisit the same destination. If you need to investigate further, check any available connection details in Data and compare the destination domain, matched rule, and policy to determine how the request was routed. An increase in traffic alone doesn’t prove that the request went through the selected server. If the available information isn’t conclusive, mark the result as unconfirmed rather than treating a guess as proof.

If Proxy works but Config doesn’t, focus on the active configuration, rules, and DNS rather than the server details. Keep the working server settings and check the specific match in the Rules Reference instead of repeating the entire setup.

5. Check Each Stage of Failure

First, identify where the process stopped: nothing imported, the server is listed but the test fails, system approval fails, or the connection stays on but the destination won’t load. Change one setting at a time and record the result. If it doesn’t help, restore the original setting before checking the next one. This preserves settings you’ve already verified and helps you find the right troubleshooting guide.

No Servers Appear After Import

Check whether you entered a subscription URL, a single-server share link, or a configuration file URL, and confirm that you used the matching import option. Make sure the link wasn’t truncated by a messaging app, all query parameters are present, and the access credentials are still valid. If an update returns a login page or error message, the URL may open successfully without providing subscription content the app can recognize.

Also check whether the current network can retrieve the subscription and whether the existing subscription needs to be updated in its original management portal. Start by checking the returned error; don’t keep adding the same URL, as that can create duplicate entries. When describing the issue publicly, include only the error type and hide the full subscription URL and authentication details.

Server Listed, but Tests Keep Failing

Check the address, port, and protocol first, then verify authentication fields such as the password, UUID, and encryption method. Finally, review TLS, server name, and transport settings. Check for a mistyped port, extra spaces in the password, or a missing path. All fields must match your existing server details; checking only the server name isn’t enough.

You can also repeat the same test on another network that you can access to see whether the issue is related to your current Wi-Fi or cellular connection. Check your device’s data usage settings before switching networks. If the same server fails on different networks, keep the test results and ask your existing service provider to confirm the server status and details. Repeatedly switching modes won’t fix an authentication error.

Connected, but Pages Won’t Load

First, make sure you aren’t in Direct. Compare the same destination in Proxy and Config. If only Config fails, check whether the active configuration includes an unexpected REJECT, an unsuitable DIRECT, or an incorrect fallback policy. If both modes fail, continue checking the server, DNS, and destination status rather than focusing only on rules.

For certificate errors, first check the device time, server name, and TLS settings. Don’t make skipping certificate verification your default. If only some domains fail, note the domain and time, then review the related connection details; there’s no need to clear all configurations. DNS changes can affect domain resolution, but make them only when the error points to DNS rather than stacking settings blindly.

Keep Useful Details for Next Time

Record four things: the step where the failure occurred, the Global Routing mode in use, the exact error shown by the app, and what changed after switching networks or modes. Never include passwords, UUIDs, full subscription URLs, or QR codes containing credentials. Before asking for help, make sure you can describe what worked and what failed—not just the color of the switch.

After your first connection, routine use mainly involves maintaining existing subscriptions, checking the selected server and configuration, and watching for changes when issues arise. For more on connections and imports, see the FAQ. For terms such as On Demand and FINAL, see the Glossary. Configuration details are covered in the Rules Reference. You’re done with this guide when an existing server connects, you can verify a real request, and you know where to start troubleshooting.

Shadowrocket Setup Guide