This guide uses an iPhone or iPad for the first-time Shadowrocket setup. It’s for users who already have their own connection details or subscription but haven’t connected yet. Check your details, approve the VPN configuration, select a SERVER entry, and review Global Routing. Then use Connectivity Test and a real request to distinguish a connected state from successful access to a specific destination. Other platforms can use the same troubleshooting approach, but their system permission steps differ from iOS.
1. Before connecting: Know the app, connection details, and configuration
On iPhone and iPad, installing Shadowrocket doesn’t give you a working connection by itself. The app handles traffic, SERVER stores your own server details, and Config manages routing rules. These serve different purposes. Seeing Not Connected or an empty SERVER list the first time you open the app doesn’t mean the installation failed.
This guide assumes you already have your own provider and subscription. This site does not provide, sell, or recommend servers, subscriptions, or providers. Subscription URLs often contain access credentials, so treat them as sensitive. Don’t post the full URL, QR code, or screenshots that show passwords in public forums.
- Home: Check the connection toggle, Global Routing, Connectivity Test, and SERVER to make everyday selections and review connection status.
- Config: Check that a rules configuration exists and is selected, and that its referenced policies are available.
- Settings: Review app settings. For automatic connections, go to Settings → On Demand and check the trigger conditions.
2. VPN configuration permission: Approve it when you first connect
On iPhone and iPad, the system usually asks to add a VPN configuration when you first turn on the connection; the prompt may not appear as soon as you open Home. Once approved, iOS can route traffic to Shadowrocket for processing according to its configuration. This does not authorize a server account or create a subscription or server details for you.
-
Check your details
Go to Home and confirm that SERVER contains one of your connection entries. If you haven’t added one yet, import it using your existing details before testing the connection.
-
Select an entry
On Home → SERVER, tap the entry you want to test and check its name and selection indicator. An entry appearing in the list doesn’t mean it’s selected.
-
Turn on the connection
Tap the connection toggle at the top of Home. If the system asks to add a VPN configuration, confirm that the prompt is for Shadowrocket, then allow it.
-
Complete verification
If the system asks for your device passcode or biometric authentication, follow its instructions. This confirms a system action on your device; you don’t need to enter your subscription password.
-
Check the status
Return to Home and see whether the status has changed from Not Connected. Then run Connectivity Test and make a request to your actual destination to check access.
On iPhone and iPad, adding a VPN configuration is not the same as installing a certificate or enabling HTTPS decryption. You don’t need to install an additional certificate for the initial connectivity check. If a separate action prompts you to install a certificate, stop and check what it’s for instead of treating it as a required first-connection step.
3. Home toggle and SERVER: Check status and selection separately
On the iPhone and iPad Home screen, Not Connected means the app’s VPN connection isn’t currently established. SERVER displays the connection entries you can choose from. The toggle, entry selection, and destination access are three separate checks: even with the toggle on, confirm the selected entry and routing mode.
Check Home status
- Not Connected
- Not connected yet? Check the toggle and system permission first.
- Global Routing
- Confirm whether the current mode is Proxy, Direct, Config, or Scene.
- Connectivity Test
- Review the test result, but don’t treat a single result as conclusive for all destinations.
Check the connection status first, then decide how traffic should be handled.
Check SERVER details
- Selected entry
- Check the name and selection indicator, not just the entry’s position in the list.
- Address / Port
- Match the details you received. Don’t guess the port based on the protocol name.
- Type
- Make sure it matches the protocol in your connection details; switching protocols isn’t a troubleshooting method.
Check the server address, port, and authentication details together.
On iPhone and iPad, if you already have a subscription, tap “+” in the top-right corner of Home to open Add Server. Choose Subscribe under Type, enter your own subscription URL, and save. The example URL https://example.com/sub?token=xxxx is for recognizing the format only and won’t connect. After saving, check that the subscription expands into SERVER entries. Update it, then confirm which entry is selected.
- When adding a server manually, fields differ for Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard. Follow the details provided for your connection.
- Updating a subscription refreshes the connection details returned by that subscription. It doesn’t select an entry or change the active rules configuration.
- If the list is empty, check the import result and make sure the address is complete. If an entry is present but the connection fails, check the protocol, port, authentication details, and current network.
4. Global Routing: Choosing among the four modes
On iPhone and iPad, Home → Global Routing determines how intercepted traffic is handled; it isn’t a server speed test. When troubleshooting for the first time, keep the same SERVER entry and change only the routing mode. Changing the entry and rules at the same time makes results hard to compare.
Config
RecommendedHandle requests using the rules and policies in the currently enabled configuration. This works best after checking the configuration source, rule contents, and policy references. Don’t assume an unchecked configuration is correct.
Best for: Everyday use with a working rules configuration that routes traffic by destination.
Proxy
Handle intercepted traffic through the proxy to temporarily rule out Config rule selection as a variable. This does not guarantee that traffic from every app will be intercepted.
Best for: Checking whether the proxy connection works while keeping the same entry selected.
Direct
Handle intercepted traffic by connecting directly. A VPN connection being active and a request using the proxy are different things; the system VPN indicator alone doesn’t tell you which route traffic takes.
Best for: Comparing with a direct connection on your current network to distinguish network issues from proxy path issues.
Scene
Use a preset scene to determine how connections are handled. Check your existing scenes and their conditions first; Scene isn’t a switch that automatically fixes connection problems.
Best for: Using a scene you’ve already configured and verified.
In Config mode on iPhone and iPad, rules are matched in order. The examples below show rule-line structure only; they aren’t a complete configuration file or instructions to replace your current configuration. PROXY must resolve to an available policy in the active configuration. A correctly written rule doesn’t replace checking the configuration as a whole.
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXYDOMAIN-SUFFIXmatches domain suffixes. In this example,example.comand its subdomains match the corresponding rule.IP-CIDRmatches a specified IP range. The example uses a private address range; don’t enter a domain name as a network range.GEOIPmatches using IP geolocation data. Results depend on the geolocation database used, so check that it is up to date.FINALis a fallback rule at the end. If placed earlier, it prevents later rules from matching as intended.
5. Connectivity Test: Read test results separately from real-world access
On iPhone and iPad, Connectivity Test provides clues for diagnosing a connection; it can’t confirm that every domain, port, and app request will work. The test and your actual requests may use different destinations or routes. Record the test result, then compare it with a real request to the same destination instead of relying on a single latency value.
How to troubleshoot two common cases
Still showing Not Connected
- Confirm that you completed the system prompt to add a VPN configuration.
- Check that the Home toggle doesn’t immediately switch back off.
- Check whether another VPN connection is already in use.
- Confirm that SERVER has a usable entry selected.
Connected, but access fails
- Check Global Routing first and make sure Direct wasn’t selected by mistake.
- Keep the same entry and compare Proxy with Config.
- Check DNS resolution, rule matches, and policy references.
- Switch between Wi-Fi and cellular, then repeat the same request.
Change one condition at a time and record the network, entry, routing mode, and destination so you can compare results.
On iPhone and iPad, if the same destination works with the same entry in Proxy mode but fails in Config, check the active configuration, earlier rules, and policy references before deleting a subscription. If both modes fail, check the server details, authentication information, and current network. This result alone doesn’t identify the cause.
- Keep the network, SERVER entry, and test destination the same, then record the Connectivity Test result.
- Make one real request and note whether it fails to resolve, times out, or returns a specific server error.
- Change only Global Routing, then repeat the same request. Don’t update the subscription or switch configurations at the same time.
- To investigate further, review the request log available in the app and check the destination, matched rule, and policy used.
6. On Demand and final checks for first-time setup
On iPhone and iPad, first verify that a manual connection and disconnection both work. Then go to Settings → On Demand to configure connections by condition. On Demand controls connection triggers; it doesn’t fix server settings and isn’t the same as Scene in Global Routing. If the connection comes back automatically during troubleshooting, check the existing On Demand conditions first.
- Test manually first: Confirm that the Home toggle connects and disconnects properly, and note which SERVER entries work.
- Check conditions next: Go to Settings → On Demand and review each network condition in the current configuration. Don’t add automatic connection settings before you’ve established a working connection.
- Test on another network: Switch from Wi-Fi to cellular and check whether the behavior matches your expectations. One successful network switch doesn’t prove that every network will work.
- Keep variables to a minimum: During first-time setup, stick to one entry and one configuration. Adjust rules or automatic connection conditions after confirming they work.