01 · Add Server: Add an Existing Server

Open Shadowrocket, go to Home, and tap the add button to open Add Server. Choose a Type before filling in the other fields. It must match the protocol in your server details—do not guess based on the server name. Shadowsocks, VMess, VLESS, Trojan, WireGuard, and other types require different fields. After changing Type, check the required fields shown on screen again.

Enter the server address and port in their respective fields. The address field usually accepts only a hostname or IP address; do not paste a full web address with the port included. Enter the authentication details exactly as provided, checking for leading or trailing spaces, line breaks, and capitalization. If your details include TLS, a transport method, or other parameters, enter each one in the corresponding field. Do not save after entering only the address and authentication details.

Confirm that Type matches your server details, then check the address, port, and authentication fields.
Check any additional parameters. Do not enable options that are not specified in your server details.
Add a recognizable label, save, and return to Home.
Tap the entry you just added and confirm it is selected.

A successful save only means the app accepted the fields; it does not confirm that the server has authenticated successfully. Do not change several parameters in quick succession. Keep this entry as is and use the same verification steps later. If your server details are provided as a QR code, use Scan QR Code to read it, then verify the protocol, address, and additional parameters before saving.

Once the server appears in Home, you can skip the subscription step and continue to check Config. If you want to use a subscription to manage multiple server entries, import it in the next step instead of entering the same details one by one.

A subscription URL provides server entries; it is not a regular webpage describing a service. Copy the complete URL from your own service provider's details. In Home, open Add Server, set Type to Subscribe, and paste the URL into the URL field. Add a recognizable label if you like, check the details, and save. Wait for the app to retrieve and parse the subscription.

Do not manually remove parameters after the question mark when pasting the URL. Some parameters identify your access, and removing even one character may cause the request to fail. If the copied URL includes quotation marks, leading or trailing spaces, or line breaks, compare it with the original and correct it. Do not share a live URL containing personal authentication parameters for someone else to test.

After saving, return to Home and check whether server entries appear in the corresponding subscription group. Seeing the group name with no entries does not mean the import succeeded. Distinguish between a saved subscription URL and a parsed server list. When the list appears, expand the group, select the entry you want to use, and continue to the connection steps.

Review After Updating a Subscribe Entry

If your service provider says the subscription has changed, or an existing entry may be out of date, use the action menu for that subscription in Home to update it. Menu location and appearance may change between app versions; follow what you see in the app. After updating, check the list and selection again. Entries may have changed or been removed, so do not assume the previous selection is still valid just because the update finished.

Repeatedly refreshing in quick succession is not a substitute for troubleshooting. If an update fails, note the error and check whether your device can reach the subscription URL and whether your service provider has mentioned access restrictions. If the subscription list looks normal but the server will not connect, check the server parameters and connection path rather than immediately deleting the entire subscription.

To distinguish a URL format issue from a server response issue, read How to Troubleshoot a Failed Subscription Import or an Empty Server List. After importing, check the configuration file that determines how rules are handled.

03 · Config: Check the Current Configuration

Open Config to see which configuration is active. Server entries determine which connections are available; the configuration file defines rule handling and other settings. They are separate. A successful subscription import does not mean the rules in Config have changed. Likewise, selecting a configuration file does not fill in missing server authentication details.

For your first setup, check the current configuration before making changes. You do not need to replace the entire file just to test a connection. If you already have a trusted configuration and understand its purpose, follow its instructions to import and select it in Config. Keep the original file and save a copy before editing. A configuration from an unknown source may change how traffic is routed; do not enable one based on its filename alone.

The brief rules below illustrate how to read rule order; do not paste them over your current file. example.com is a sample domain. Check the current configuration and app settings to confirm which proxy PROXY refers to.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

In Config mode, requests are checked against rules in order. The first rule matches by domain suffix; the second matches by destination IP range. FINAL handles requests that did not match any earlier rule. A rule appearing in the file does not mean it will be matched: rules earlier in the list and the final policy matter too.

For now, just confirm which configuration is active. To review the three routing modes, see the Global Routing steps. For details about app availability, storefront regions, and restoring purchases, see the installation guide.

04 · Global Routing: Choose a Routing Mode

Return to Home and open Global Routing. This setting determines how requests are handled; it does not import servers or fix incorrect authentication fields. The three modes are Config, Proxy, and Direct. Choose one for your current task, then return to Home and confirm your selection.

Config: Applies the rules and corresponding policies in the active configuration file. Choose this mode when you want different destinations to use different routes. Before using it, check which configuration is active and its final policy; otherwise, a request may take a different route than expected.
Proxy: Routes requests handled by the app through the proxy. This can reduce the effect of rule differences during an initial check. It still depends on a correctly selected server and valid parameters. It cannot make an unavailable server work, and it does not guarantee that all traffic from every app is handled.
Direct: Handles requests by connecting directly, which can help you compare access over your current network. It does not turn off the app's connection switch. To stop the current connection entirely, return to Home and turn off the switch; switching to Direct is not enough.

For an initial check, try Proxy with the selected server, then switch to Config to check rule behavior. If a destination works in Proxy but not in Config, check the rules and policies before re-entering server details. If both modes fail, do not assume the server is at fault; also check the system connection status and the destination service.

After each mode change, make the same request to the same destination. Do not compare results from different pages. When testing is complete, restore the mode you intend to use and note the active configuration and server name so you can reproduce the setup later.

05 · Home: Connect and Approve the System Request

In Home, check two things: the intended server is selected, and Global Routing is set to the mode you just chose. Then turn on the connection switch at the top. The first time you connect, the system may ask to add a VPN configuration. Confirm the request was initiated by the Shadowrocket you are using, then follow the system prompts to approve it and complete device authentication.

This system approval lets the app create the required network configuration. It is not a purchase prompt and does not confirm server authentication. If you previously canceled the request, return to Shadowrocket and try connecting again, then follow the system prompts. If the switch does not stay on, do not repeatedly add servers; server details and system approval are separate troubleshooting steps.

After approving the request, return to the app and check whether the switch and connection status remain active. A VPN status indicator means the relevant network connection has been established; it does not by itself confirm that a website is reachable or that a particular Rule matched. Continue to the next step to test access rather than relying on the status indicator alone.

If another VPN connection is already active on the device, identify which connection is in use before comparing results. If the connection resumes automatically on certain networks, check whether On Demand is enabled in Settings. During initial troubleshooting, note its current setting so automatic connection behavior is not mistaken for a switch problem. Follow your organization's requirements for managed devices.

06 · Connectivity Test: Verify the Connection

Return to Home, run Connectivity Test, and review the results for the server you added. The test method and current network can affect the results, so confirm the settings used for this test. A response means the server passed that specific test; it does not confirm successful authentication, access to the destination service, or that every request will work.

Next, open a browser and visit a service you are authorized to use where you can clearly tell whether it has loaded. Reload the page and confirm that fresh content appears; do not rely only on the page title or cached images. If the destination requires a login, check the login status separately from the network connection. A permissions message does not automatically mean the connection failed.

Note the network, server, Global Routing mode, and active Config used for the test.
In Proxy, revisit the same destination to confirm the basic proxy path.
Switch to Config, revisit the destination, and check how the rules handled the request.
Use Direct for comparison if needed, then restore your intended mode.

To check whether a rule took effect, review the connection records or logs available in the app. Find the request you just made and check the matched rule and its policy. Matching DOMAIN-SUFFIX and falling through to FINAL are different outcomes. Even if both happen to use the same policy, they are not the same rule match.

A latency test reflects response time under a particular test method; it is not the same as actual transfer speed. If the in-app test succeeds but a webpage does not load, also consider DNS, the destination service status, and authentication. Change one condition at a time and repeat the same test to identify whether the result depends on the server, network, or configuration.

07 · Troubleshoot by Failure Point—Don't Reset Everything

Start by describing the failure in one sentence: “The subscription parsed no entries,” “The switch will not stay on,” “The test gets a response but webpages will not load,” or “Only Config mode fails.” Each points to a different part of the setup. Save the current configuration and relevant records before making changes. Do not delete the subscription, switch servers, change DNS, and replace rules all at once; you will not know which change made a difference.

Subscription Saved, but the List Is Empty

Return to the Subscribe steps and check that the URL is complete, is a subscription URL, and still has valid access permissions. If the response is a login page or an error message, the app may not be able to parse it as a server list. Contact your service provider to confirm the format or access permissions; you do not need to change Global Routing first.

Server Listed, but Connection Fails

First check that the correct entry is selected, then verify Type, address, port, authentication details, and additional parameters one by one. If the entry is managed by a subscription, update it once and select it again. For a manually added entry, compare each field with the original details. If the result changes on another available network, note the difference rather than immediately changing the authentication fields.

The Switch Won't Turn On or Quickly Turns Off

Check whether system approval is complete, another VPN connection is active, or the device has management restrictions. If the switch turns back on automatically, check the On Demand conditions. Resolve system connection issues before testing websites; changing rules repeatedly will not fix incomplete authorization.

Proxy Works, but Some Destinations Fail in Config

Confirm that Config is using the expected file, check which rule matched the destination request, and review the FINAL policy. Domain rules and IP range rules use different matching criteria, and DNS results can affect what happens next. Test a change to one rule in a copy of the configuration; do not replace the entire rule set for a single destination.

The Test Gets a Response, but the Service Still Doesn't Work

Check whether the destination service is working, your account has access, and the app's records show any authentication, parsing, or connection errors. When contacting your service provider, include the time of the issue, network type, protocol type, and the comparison steps you have completed. Hide your subscription URL, password, and other authentication details. Treat the test result as one clue and consider it alongside the actual request.

To update an existing subscription, go straight to the subscription update steps. To compare routing behavior, see the Global Routing guide. For a new device, reinstalling, or purchase history issues, read the App Store installation guide instead of troubleshooting server parameters again.

Shadowrocket Setup Guide