At a glance

This guide is for iPhone and iPad users who already have their own service and subscription and are preparing to connect with Shadowrocket for the first time. The steps are: confirm a server is available, choose Global Routing, approve the system prompt, run Connectivity Test, then verify with an actual request. An enabled switch, server latency, and successful website access are separate checks and should be verified individually.

1. Before Connecting: Check for an Available Server on Home

After opening Shadowrocket, start on Home. A server name in the list only means the entry has been saved; it does not confirm that the address, credentials, or service are valid. For your first connection, use a configuration you already have that is still active. Avoid changing the protocol, port, and rules all at once while troubleshooting.

Use Home to select a server and control the connection. Config is for managing rule configuration files, while Settings is where you check app options such as On Demand. A server subscription and a rule configuration are separate: the former updates server entries, while the latter determines how requests are routed. Importing one does not automatically configure the other.

  1. With the connection off, confirm that your device can access websites allowed on the current network. If public Wi-Fi requires a sign-in page, complete network authentication first.
  2. On Home, find an existing server and tap the entry you want to test. Make sure the selection indicator is on that entry, rather than merely opening its edit screen.
  3. Open the server entry’s edit screen and check the server address, port, and authentication details. Use the port provided by your service provider; do not assume it is 443 just because TLS is enabled.
  4. If the entry came from an existing subscription, first check that the most recent update succeeded, then confirm the server is still listed. A successful subscription update only confirms that the subscription content was retrieved; it does not mean every server in it can connect.

2. Choose Global Routing: Decide How Test Requests Should Be Routed

Open Global Routing on Home and note the current selection. Config routes requests according to the rules in the active configuration; it does not automatically mean “proxy some traffic and send the rest direct.” The actual route depends on the matching rule and policy. If both rules and the server may be causing a first-connection issue, temporarily select Proxy to narrow down the cause, then restore your usual setting after testing.

Config

Recommended

Routes requests according to the rules in the active configuration file. Before using it, confirm that the configuration is selected, the policies referenced by its rules are available, and the destination of FINAL is correct.

Best for: users with an established rule configuration who want to use it for everyday connections after testing

Proxy

Routes requests handled by the proxy through the proxy path, reducing interference from rule-based routing during tests. It does not replace system authorization or fix incorrect server credentials.

Best for: troubleshooting a server connection for the first time or comparing results with Config

Direct

Uses a direct connection. A website loading in this mode does not prove that the selected server is working or indicate whether the proxy connection succeeded.

Best for: checking the device’s basic network connectivity

Scene

Applies the settings associated with the configured scene conditions. To understand how the connection behaves, also check whether the current network matches the expected scene.

Best for: users who have configured scene conditions and can confirm which one is active

Diagnosis: Proxy works but Config does not—check the rules next

Keep the same server, network, and test target; change only Global Routing. If the result changes with the mode, check which policy Config matches before re-entering all server details.

3. Turn On the Connection and Approve the VPN Configuration

Return to Home and turn on the connection switch at the top. When connecting for the first time, the system may ask you to allow a VPN configuration. This grants permission to create a system network tunnel; it is separate from subscription authentication and your server password. After allowing it, complete any device authentication requested by the system, then return to Shadowrocket to check the connection status.

  1. Confirm that the server selected is the one you want to test, then turn on the connection switch.
  2. When the system prompts you to add a VPN configuration, tap Allow and complete any requested authentication. Do not enter your server password in the device authentication prompt.
  3. Return to Home and make sure the switch stays on. Check for an error message or an immediate disconnect.
  4. If you previously denied permission, turn the switch on again to retry. If needed, check the VPN configuration under Settings → General → VPN & Device Management. On managed devices, follow your organization’s policies and do not remove managed configurations yourself.

A switch that stays on indicates that the system tunnel has been created or is active; it does not mean every request will succeed. The server handshake, DNS resolution, rule matching, and destination website response can each fail independently. Run Connectivity Test next rather than relying only on the VPN icon in the system status bar.

4. Run Connectivity Test: Distinguish Latency from Actual Connectivity

Run Connectivity Test on Home and note the result when it finishes. Before interpreting it, check which test method was used: a TCP probe mainly checks whether a connection endpoint is reachable, while an HTTP-based test also involves a destination request and response. They cover different stages. A single latency value is not a download speed and does not prove that every website, UDP request, or long-lived connection will work.

If the test runs probes in bulk from the server list, its results may include servers that are not selected. Find the result for the currently selected server and compare it with what happens when you access the service. For connections such as Hysteria2 and WireGuard that rely on UDP, a basic TCP port test alone cannot determine whether the protocol is working correctly.

ResultWhat it tells youWhat to do next
A latency value appearsThe selected test completed; this does not directly indicate bandwidth or confirm that all services are availableKeep the connection on and test by opening a website you actually need to use
TimeoutThe test did not finish within the allotted time; the cause has not yet been identifiedCheck the underlying network, test target, server address, and port, then test again
Connection refusedUsually means the endpoint or an intermediary explicitly refused the connectionCheck the port and whether the service is listening; do not try to mask the issue by changing rules
A TLS or certificate error appearsThe handshake or certificate validation needs to be checkedCheck the device time, server name, and TLS parameters; do not disable certificate validation as a first step
Test passes, but the website does not loadThe test target and the actual destination may use different rules or encounter different network conditionsCheck the rules for the failing domain, its DNS results, and the connection log

Run the test three times and record how many succeed and any error messages, rather than keeping only the fastest result. For example, if two of three tests time out, investigate stability first. If all three finish but one website keeps failing, narrow the troubleshooting to that destination and its rules. This is a way to record results, not a measured claim about any server.

5. Verify with the Same Request: Separate Network Issues from Configuration Issues

Change only one condition at a time during testing. Keep the server and Global Routing fixed, then access the same target over Wi-Fi and cellular data. Next, keep the network and server fixed and compare Proxy with Config. This helps identify whether the difference comes from the access network or the selected rules.

Verification Plan: Test Wi-Fi and Cellular Separately

Wi-Fi
  • Complete any public network sign-in and confirm that the basic network works with the connection off.
  • Record the current server, Global Routing selection, and Connectivity Test result.
  • Make an actual request to a fixed target and keep a record of any error message.
Cellular Data
  • Confirm that the device supports cellular connectivity and that the app is allowed to use cellular data.
  • Keep the same server and mode, then repeat the same test.
  • If the issue occurs on only one network, check that network’s access restrictions first.

If your iPad does not have cellular connectivity, retest on another trusted Wi-Fi network. When switching networks, do not also update the subscription or change the protocol.

If a specific destination fails only in Config, open the active configuration file in Config and check [Rule]. Rules are usually matched from top to bottom, so put specific domains before broader rules and place FINAL last. The following is a syntax example, not a complete replacement configuration:

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

DOMAIN-SUFFIX matches a domain and its subdomains; IP-CIDR matches an IP range, and no-resolve in the example means not to trigger an additional domain lookup for that IP rule; GEOIP matches against an IP geolocation database; FINAL handles requests that did not match earlier rules. The example’s PROXY must correspond to an available proxy policy in the active configuration. If a rule points to another policy group, selecting a different server on Home may not change that group’s selection.

6. Common First-Connection Issues: Troubleshoot by Symptom

The switch turns off as soon as I turn it on. Should I change the server first?

First check whether you approved the system VPN configuration and selected a valid entry on Home. Note any message shown when the connection drops and check for conflicts with existing VPN connections. If the system tunnel cannot be established, do not start by changing DNS or the entire rule set.

Connectivity Test shows a value. Why won’t the website load?

First make sure Global Routing is not set to Direct, then check which policy the active configuration applies to that domain. The test result applies only to that test. If one website fails while other destinations work, check that site’s DNS resolution, rules, and service status instead of assuming the entire connection is down.

The subscription updated successfully. Why does the connection still time out?

The subscription update and the server connection may use different destinations. Return to Home and check the selected entry’s address, port, and credentials, then confirm the service is still active. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard use different fields; changing only the protocol name does not convert one configuration into another.

It reconnects after I turn it off manually. Is the switch broken?

Check the on-demand connection settings under Settings → On Demand. Turn the setting off temporarily, disconnect manually, and observe what happens. If automatic reconnection stops, the previous connection was being triggered by an on-demand condition. Restore the setting after testing if it suits your network needs.

If you need to investigate further, note the network type, protocol name, Global Routing selection, test method, exact error message, and whether only one destination fails. Before sharing these details, hide the full subscription URL, passwords, keys, UUIDs, and other authentication information. With these details organized, consult Troubleshooting or the relevant settings in Configuration Reference to avoid unrelated changes.