Official Manual · Getting Started Import and use an existing configuration

Shadowrocket
Import and Connection Guide

Follow the steps in order: import, choose a routing mode, connect, and verify access. First confirm that a server is reachable, then check that the rules behave as expected.

01 · Add Server: Add a server or import a subscription

This guide is for iPhone and iPad. After opening Shadowrocket, go to Home and check whether a server is already listed. If the list is empty, do not turn on the connection yet; first save your existing server details in the app. Subscription links, individual server links, and Config files serve different purposes, so identify which type of information you have before importing it.

A subscription link is usually provided by a service provider to retrieve and update a group of servers. A single server entry contains the connection details for one server. A Config primarily organizes rules and related settings. Pasting a subscription link into a server address field, or using a Config file URL as a Subscribe link, can cause the import to fail. If you cannot identify a link by its appearance alone, check the original configuration instructions instead of trying different import options at random.

Have a subscription link? Choose Subscribe

  1. In Home, tap the plus button in the upper-right corner to open Add Server. Tap Type, then choose Subscribe.
  2. Paste your complete existing subscription link into the URL field. If you want to add a note, enter a name that will help you identify it later. Do not put the link in the note field.
  3. Tap the Done button to save, return to Home, and wait for the subscription to load. Then check whether server entries appear in the group.
  4. Expand the relevant group and tap a server to select it. Seeing a subscription group does not mean that a specific server entry is selected for connection.

After pasting, check that the beginning, end, and query parameters are intact. Do not include chat text, line breaks, or trailing punctuation. Subscription links may contain access credentials; use them only in the intended field, and never include them in public screenshots, web pages, or issue descriptions. If the subscription fails to load after saving, keep the original link and follow the troubleshooting steps at the end of this guide. Creating multiple copies of the same subscription only makes them harder to identify.

If the subscription contents change, use the relevant subscription group controls in Home to update it, and check the update message. After updating, verify the selected server again: the previous entry may have been replaced or removed. Updating refreshes the server list, but does not confirm that a new entry can connect or replace the rules in Config.

Have server details? Enter them according to Type

If you have details for a single server, tap the plus button in Home to open Add Server. Under Type, choose the protocol that matches the original details, then enter the address, port, and authentication fields. For example, VLESS, Trojan, and WireGuard use different fields. Matching addresses and ports do not make the protocols interchangeable. Save the entry, return to Home, and select the server.

Compare each field with the original details, paying attention to capitalization, spaces, and port numbers. If the details include TLS, SNI, a transport method, or a path, enter those values in the corresponding fields. Do not omit parameters just to shorten the form. If TLS verification fails, check that the name matches the certificate rather than weakening verification to bypass the error. If a field is unclear, see the Quick Reference before continuing.

If you already have a QR code for a server, use Scan QR Code and grant camera access when prompted. After scanning, check the Type, address, and port against the original details. A QR code is simply a way to carry configuration information; it does not mean the connection has been tested. Once you have imported your configuration using either method, decide how traffic should use the server.

02 · Global Routing: Choose how traffic is handled

Return to Home, tap Global Routing, and check the current selection. This setting determines how traffic is handled; it does not provide a server. The three modes are Config, Proxy, and Direct. Before testing, decide whether you want to check the server itself or an existing set of rules; the right mode depends on your goal.

Config: Follow the active configuration rules

Config is suited to everyday use when rules determine which requests use a proxy and which connect directly. Before selecting it, open the app’s Config page and make sure the configuration file you need is selected. A file appearing in the list does not mean it is the active configuration. Check the selection indicator and confirm that the file comes from configuration details you recognize.

Rules are generally matched in the order they are written, and the matching policy determines how each request is handled. The snippet below illustrates “proxy specified domains and connect directly otherwise.” It is not a complete configuration to create for this guide, and it does not provide a server:

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

DOMAIN-SUFFIX matches domain suffixes; PROXY and DIRECT specify how to handle traffic; and FINAL provides a fallback. The example domain example.com is for syntax illustration only. If your existing Config works, do not overwrite the entire file just to make your first connection. For a deeper explanation of rules and configurations, see the Quick Reference.

Proxy: Check whether the current server can handle access

Proxy is useful for temporarily ruling out rule-matching issues when checking whether proxy traffic can reach a site. Select a server, switch to Proxy, and test the same website. If it works in Proxy but not Config, check the active configuration and its rules instead of immediately importing all servers again. Proxy cannot fix incorrect authentication details or make an unreachable server respond.

Direct: Check direct access on the current network

Direct sends requests over the current network, providing a useful comparison. It does not select a server automatically, and selecting an entry in Home does not route direct requests through that server. Use Direct to test a site that the current network can normally reach. This helps distinguish a basic network problem from a proxy connection issue.

After testing, restore the mode that suits your everyday needs. If you need rule-based routing, return to Config and confirm the active configuration. Do not assume that turning on the connection switch resets Global Routing from a temporary test mode. Once you have confirmed the mode, continue to system authorization and connection.

03 · Home: Turn on the connection and authorize it

Return to Home and check two things: whether the correct server is selected and whether Global Routing matches your test. For the first connection, keep the network stable. Avoid switching between Wi-Fi and cellular while changing server details, or it will be harder to tell what caused a failure.

  1. Turn on the connection switch at the top of Home.
  2. When connecting for the first time, the system may ask to add a VPN configuration. Read the prompt, confirm that Shadowrocket is the requesting app, then tap Allow.
  3. Complete any device passcode or identity verification requested by the system, then wait for the app to reopen.
  4. Check that the connection switch remains on and that the system VPN connection is established.

This authorization lets the system route the relevant network traffic through the app. It is not a subscription import confirmation or another app purchase step. Saving a server entry alone usually does not authorize a VPN configuration; the system prompt appears when you actually start a connection for the first time. If you cancel the prompt, the connection may not proceed. Return to Home and try again, completing the authorization.

If the switch turns off immediately after you turn it on, first confirm that authorization is complete. Then check the VPN configuration section in system Settings. Menu locations may change with the system interface, so follow what appears on your device. If another VPN connection is active, disconnect it before testing. Restrictions on managed devices may also affect VPN configurations; follow your device management requirements rather than repeatedly resetting all network settings.

An established VPN status only means the system tunnel is up. It does not confirm server authentication, DNS resolution, or access to the destination website. Continue to the next step and test access even after the system shows a connection indicator. If you have set up On Demand, check its trigger conditions during troubleshooting. If needed, temporarily turn it off so it does not reconnect automatically after you disconnect manually and interfere with your comparison.

04 · Connectivity Test: Verify the connection and rules

Return to Home and use Connectivity Test to check the current server. A response is evidence that the server is reachable using this test method; no response means you should check the network and server details further. Results depend on the test method and target, so one number cannot tell you whether every website is accessible. Response time is not the same as actual download speed.

Next, open a browser and visit a website known to work on your current network to confirm that the device is online. Then visit the site you want to test. Load a fresh page if possible, so a cached page is not mistaken for a successful new connection. If only one website has a problem, check whether that site itself is available before attributing the issue to the entire app.

  1. Check the basic network: Turn off the app connection and see whether a known-working website opens normally.
  2. Check the server: Reconnect and use Proxy to request the same destination. Check whether the current server can reach it.
  3. Check the rules: Switch back to Config, visit the same destination, and compare the result.
  4. Review traffic handling: Check the connection records available in Data. If the destination and policy are shown, confirm that they match your expectations.

When reviewing records, match each test action to its timestamp. A page may request content from several domains; one rule matching the main domain does not mean that images, APIs, or sign-in requests use the same policy. If a page loads with some content missing, identify the domain and policy used by the failed requests rather than simply broadening the rule for the main domain. Changes in Data show that traffic is flowing, but do not by themselves prove that a specific website matched the intended rule.

Change only one variable at a time. Keep the network, server, and destination fixed, then change Global Routing. This helps distinguish an unavailable server from a rule that did not match. After testing, restore your usual mode and note the working server, active Config, and test results. That gives you a baseline to compare against if anything changes later.

05 · Common issues: Troubleshoot in order

First identify where the process stopped: no entries loaded from the subscription, the switch will not stay on, Connectivity Test gets no response, or only website access is affected. Each symptom points to a different step. Keep your current configuration and original details, then check the following in order. Avoid clearing the list, replacing Config, and changing DNS all at once before identifying the cause.

Subscribe saved, but no servers appear

First confirm that the URL is a complete server subscription link, not a provider’s information or account page. Check for extra spaces or punctuation and make sure query parameters were not omitted, then review any error message shown during the update. The list may remain empty if the current network cannot reach the subscription URL, the server returns an error, access credentials have expired, or the response is not in the expected format.

“Subscription updated successfully” and “server can connect” are two separate checks. If the link fails to load, ask the original service provider to confirm its status and response format. If entries appear, continue to the server test. When describing an issue, share the error type but keep credentials in the subscription link private. For more subscription error categories, see the FAQ.

Server appears, but Connectivity Test fails

First disconnect and confirm that the current network works, then check the server address, port, Type, and authentication details. For manually entered entries, verify TLS, SNI, and transport parameters. For subscription entries, update once and confirm that the selected server is still listed. If you have another server that is already known to work, compare it on the same network using the same test method.

Server reachability can vary between networks. If a connection fails on Wi-Fi but works on cellular, record each result separately. After switching networks, reconnect before testing. Do not treat a single timeout as proof that all configurations are broken, and do not change encryption or authentication fields without a clear reason.

Switch is on, but websites won’t load

First check Global Routing. Requests in Direct do not switch to a server just because one is selected. In Config, check the active configuration and the policy matched by the destination. Temporarily use Proxy to test the same site. If Proxy works but Config does not, check rule order, policy targets, and fallback handling first. If both fail, check the server and DNS.

DNS resolution problems can also prevent websites from loading. Keep your current DNS settings and note the error first. Once you have confirmed the server details, change one setting at a time if needed. Do not change several DNS options to troubleshoot a single domain. For questions about configuration files, App Store access, or how purchases work, see the Quick Reference and App Store Guide. This page focuses on the steps for making your first connection.

Only some websites or apps have issues

Narrow the test down to a specific request. Visit the same destination in a browser, then compare Proxy and Config. Check any available destination and policy details in Data to see whether the affected content uses other domains. Sign-in, images, and video may use different addresses, so a working homepage does not mean every feature is working.

Finally, restore any Global Routing, On Demand, or Config settings changed during testing. If you need further help, note the network, the step that failed, the selected mode, any error message, and the comparison test results. Remove subscription credentials, passwords, and personal information. A reproducible sequence of steps is more useful for troubleshooting than a screenshot of the connection switch.