Add Server: Add a Server or Import a Subscription
You’re done when a selectable server entry appears under SERVER on Home.
After opening Shadowrocket, stay on Home and find Add Server or the add button on the screen. First, identify which details you have: a subscription link imports a group of servers, while individual server details must be entered field by field. They are not interchangeable. Do not enter a subscription link in Host or submit a server address as a subscription URL.
Have a Subscription? Choose Subscribe
Go to Add Server, open Type, and select Subscribe. Enter the complete subscription link you received from your own provider in URL. If you add a note, use a name that helps identify its source. Check for spaces, line breaks, or missing characters at either end of the link, then save and wait for the content to load. Authentication details in the link are private. Do not post them in public forums or include them in screenshots you share.
After saving, return to Home and check whether servers appear in the relevant group. If you see a subscription name but no server entries, the import may not have completed; check the on-screen message to confirm that the subscription content was retrieved. To refresh existing entries, use the update action for that subscription group. Wait for it to finish, then check for changes. Updating a subscription and updating the app are separate actions: the former retrieves your subscription content, while the latter is done through the App Store.
Add a Server Manually: Check Fields for the Selected Type
If you have details for an individual server, select the specified protocol under Type, then enter Host, Port, and the authentication fields. The screenshot shows one form with Password and Method; other protocols may have different fields. Do not copy fields from the screenshot if they are not used by your protocol. Use the domain or IP address provided by your service provider for the host, enter the corresponding port number, and match the encryption method and authentication details exactly.
If you have a supported QR code, scan it with Scan QR Code, then check the detected protocol and fields. Import from Cloud JSON is a separate import option; it does not mean that arbitrary text can be imported. Before saving, make sure the details match the selected import method. If you are unsure what a field means, check the glossary. For more about protocol settings, see the protocol reference. Do not guess at fields by repeatedly trying different values.
After adding a server, select the entry you want to test under SERVER and make sure the selection indicator is beside the right server. Do not bulk-edit other servers or turn on On Demand yet. First, decide how requests should be routed.
Global Routing: Choose a Routing Mode
You’re done when you know the current routing mode and whether it uses rules from a configuration file.
Return to Home and open Global Routing. This controls how connection requests are handled overall; it is not where you select a server protocol. The three modes are Config, Proxy, and Direct. To route different websites according to rules in a configuration, select Config. To check whether the selected server can handle proxy requests, you can temporarily use Proxy. Direct connects directly and does not use the selected proxy server.
To understand Config, check which configuration file is active. Open the Config screen, confirm which file is in use, then review its Rule section. Importing a subscription does not necessarily provide rules that suit your needs. Server entries in a subscription and a configuration file serve different purposes: the former provides connection endpoints and parameters, while the latter determines how requests are routed.
Review Existing Rules Before Changing Them
The configuration editor shown in the official screenshot has sections such as General, Rule, and Hosts, as well as Add Rule. When getting started, review Rule first; there is no need to change every section at once. URL Rewrite and HTTPS Decryption are not required for a basic connection. Do not turn them on or add entries just to make the connection switch show as connected.
Rules are matched in order, so check both their position and the resulting policy when interpreting a request. The two lines below are examples of how to route a specified domain through a proxy and all other traffic directly. example.com is a documentation example, not a service address you need to visit. If you already have a suitable configuration, leave it unchanged for the initial test rather than replacing its rules with the examples.
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTDOMAIN-SUFFIX matches a domain suffix, PROXY specifies a proxy policy, and FINAL is the fallback when no preceding rule matches. After selecting Config, a request matched to DIRECT will not switch to the proxy just because the connection switch is on. For troubleshooting, you can temporarily switch to Proxy and compare the same destination. Restore your intended routing mode when you finish to avoid leaving test settings in place.
For this step, choose the correct routing mode and identify which configuration is active. See the glossary for more rule keywords, or read the protocol reference to distinguish protocol parameters, transport settings, and routing rules. Next, return to Home and connect to the server you selected.
Home: Connect and Authorize the System Configuration
You’re done when the system has authorized the VPN configuration and the app shows the expected connection status.
Back on Home, check which server is selected under SERVER, then confirm that Global Routing is set to the mode you chose. Adding a server does not automatically select it. If you have multiple groups, use the selection indicator to confirm the right server rather than relying on the name at the top of the list. Once both are confirmed, turn on the connection switch at the top of the screen.
The first time you connect, the system may ask to add a VPN configuration. Make sure the request comes from the Shadowrocket app you just opened, then follow the system prompt to allow it and authenticate with your device passcode, Face ID, or Touch ID. This allows the app to handle traffic through the system network extension; it does not authenticate with the server or fill in subscription details or passwords. System authorization does not confirm that the remote server is working.
If You Previously Denied Authorization
If you dismissed the system prompt, return to the app and try turning on the connection again to see if the system asks you to confirm. If it still will not turn on, check the VPN-related settings on your device. The location may vary by system version; use Settings search to find it. If you are unsure what a configuration is for, identify the app it belongs to before removing it so you do not delete a configuration that is still in use.
After authorization, return to Home. Check whether the status at the top still says Not Connected and whether the switch remains on. If the switch immediately turns off, address the error shown in the app or the system permission issue instead of tapping repeatedly. Wait for the status to settle after each attempt and note the key text in any error message to help identify where the failure occurred.
The Home screenshot shows Global Routing, Connectivity Test, and SERVER to help you locate these controls. A successful status change means the local connection process has started; it does not prove that every website is accessible or that requests matched the intended rules. Continue by running a test and visiting the destination to check whether the configuration meets your needs.
Keep your device’s network connection stable during the initial test. Avoid switching between Wi-Fi, cellular data, and multiple servers at the same time. If a problem appears after changing networks, note the status before and after the change, then retry separately. On Demand triggers connections based on conditions. Configure it for your needs only after manual connection, disconnection, and reconnection have all been tested.
Connectivity Test: Check Whether the Connection Works
You’re done when the test result, actual access, and routing policy are consistent with one another.
On Home, use Connectivity Test to check the connection. Confirm the server and routing mode first; otherwise, the result may reflect a different connection. Test methods check different things, so interpret the result in light of Test Method under Settings. A successful test does not mean every destination is reachable, and a failed test does not prove that all servers in the subscription are unavailable.
Next, open a browser, visit a destination you intend to use, and make a new request. Do not rely only on a page that was already loaded or on cached content to judge whether the connection works. If the page still shows old content, reload it or open another page on the site. Test one specific destination at a time so you can match the visit time with the connection log in the app.
Check Connection Status and Rule Results Separately
With Config selected, find the request in the connection log and check the destination domain, matched rule, and resulting policy. If you expected the request to use a proxy but it matched DIRECT, first check the rule order and active configuration. If it matched PROXY but access failed, check the selected server and destination service. The location of connection logs may vary by interface. Traffic statistics in Data can indicate activity, but an increase alone does not show which policy handled a domain.
You can narrow down the cause with a controlled comparison: keep the server, device network, and destination the same, temporarily change Global Routing from Config to Proxy, then make a new request. If it works in the latter mode, investigate differences in the rules or configuration. If both fail, check the server details, authentication, and destination response. Restore your original routing mode after the comparison.
Test destinations that should connect directly, too. Rule-based routing is not intended to send every request through a proxy; it applies the expected policy to each type of request. Once you have checked a test result, an actual destination, and its corresponding log entry, note the server and configuration that worked. There is no need to keep changing settings that are already working just to improve a single test result.
Settings: Troubleshoot by Failure Point
You’re done when you can identify the step where the failure occurs and change only settings relevant to it.
When something goes wrong, first identify the specific failure: the subscription could not be retrieved, a server was added but will not connect, the connection is on but requests fail, or only certain destinations are affected. Do not delete the subscription, replace the configuration, change DNS, and edit protocol parameters all at once. Keep the current configuration, change one thing at a time, and repeat the verification in step four to see what made a difference.
Subscription Is Empty or Fails to Update
First confirm that the device can access the internet, then check that the subscription link is complete, especially any authentication parameters omitted when copying. If an existing subscription has expired or returns no content, ask your provider to confirm its status and supported format. Re-creating the same subscription repeatedly usually will not fix a retrieval error and can leave you with multiple groups that are hard to tell apart. After updating, check whether the server entries actually changed; the subscription name remaining in the list is not enough.
The Connection Switch Will Not Stay On
First check that the system has authorized the VPN configuration, then confirm that a valid server entry is selected. If the app reports a parameter error, return to Add Server and compare the original details with Type, Host, Port, and the authentication fields. Some protocols also have transport or TLS fields; follow the requirements in your connection details rather than substituting fields with similar names. For help understanding how the fields relate, read the protocol reference before making changes.
Connected, but Access Does Not Work as Expected
First check Global Routing. Direct does not use the selected proxy server. With Config, rules may route a destination directly or reject it. If the log shows a match for REJECT, check whether the block is intentional or the rule is too broad rather than immediately switching servers. If only some domains fail, check domain resolution, rule matching, and the destination response separately. Do not reset the entire configuration because of a single problematic page.
Open Settings and review Test Method and Diagnostics to check the relevant failure point using the available diagnostic information. Options such as Proxy, TCP, and UDP each serve different purposes; they are not universal fix switches. If you are unsure what an option changes, leave its current value in place until you understand it. There is no need to change every setting when getting started.
Before Reporting an Issue, Record the Steps to Reproduce It
Note the device network type, current routing mode, whether the issue affects all destinations, the test method, and key text from any error message. Before sharing screenshots or diagnostic excerpts, hide subscription links, server authentication fields, and other private details. Comparing results for the same destination before and after a change is more useful than simply saying, “It won’t connect.”
Once manual connections and actual access are stable, consider configuring On Demand or more detailed rules. For future subscription updates, configuration replacements, or routing changes, follow the same sequence: confirm the server entry, check the routing mode, connect, and verify a request. See the glossary for interface terms. For purchase, reinstallation, or restoring a previous purchase, see How to Restore an App Store Purchase; keep these issues separate from connection troubleshooting.
