This guide helps troubleshoot timeouts and connection failures with existing servers in Shadowrocket. It assumes you already have your own provider and subscription. Check each layer in order—local network, test results, protocol settings, TLS and system time, DNS, routing, and logs—and change only one setting at a time. This helps distinguish local network, configuration, and server-side issues. Test results do not guarantee connection quality, and an enabled connection does not mean a request reached its destination.
1. Establish consistent test conditions and check the local network
A connection failure means a request did not complete; it is not a diagnosis of a specific fault. Defaults, test methods, and connection timeouts depend on what the app currently displays. Record the original settings first, and avoid changing the server, DNS, and Global Routing at the same time. Otherwise, even if access is restored, you will not know which change made the difference.
Check the local network to confirm the device can access the internet. Turn off the connection toggle on Home and try opening a page you can normally reach directly. If it still fails, complete any Wi-Fi sign-in or check cellular data permissions before troubleshooting Shadowrocket. The VPN status icon only indicates that the system tunnel is established; it does not confirm that the remote server accepted the connection.
-
Record the original settings
On Home, note the selected server and current Global Routing setting. In Config, confirm which configuration file is in use. Record when the issue occurred and the network type, but do not include plaintext passwords or subscription credentials.
-
Test a direct connection
Turn off the connection toggle on Home and use a browser to check the local network. If public Wi-Fi requires sign-in, complete the network authentication first; do not mistake an incomplete sign-in for a server timeout.
-
Pause automatic connections
In Settings → On Demand, note the current settings and temporarily disable on-demand connections. This prevents the system from reconnecting automatically after you turn off the connection manually. Restore the original settings when troubleshooting is complete.
-
Retest one variable at a time
Return to Home, select a single existing server, turn on the connection, and try the same destination. Then switch only between Wi-Fi and cellular data and test again, leaving the server and configuration unchanged.
2. Latency tests vs. actual requests
A latency test measures the time taken by a specific probe; it does not show whether an app request will succeed. Check the test method and related options shown under Home → Connectivity Test before interpreting the results. A TCP connection probe alone does not fully verify proxy authentication, the TLS handshake, the destination's response, or UDP traffic.
A test timeout also depends on what is being probed. If the test relies on a particular test address, that address may be temporarily unreachable, causing multiple servers to show failures. If browsing works but the probe fails, check the test address and method before deleting an existing configuration.
- TCP probe succeeds, but webpages fail: Check authentication, TLS, transport settings, and the policy actually applied—not just the latency value.
- One server fails while the others work: Check that server's address, port, and status before resetting all settings.
- The same configuration fails on only one network: Check that network's DNS, port access, and UDP reachability, and note what changes when you switch networks.
- Multiple servers and direct access both fail: Fix the device's basic network connection first. Repeatedly refreshing the subscription usually will not resolve an issue at this layer.
3. Check the server address, port, and protocol settings
Server settings are defined by the agreement between the client and server; there is no single correct value for every protocol. Open the relevant server's edit screen on Home and compare each field with the original configuration from your provider. Keep the original address, port, and authentication details. Do not change every port to 443 based on guesswork. Do not add URL paths or extra spaces to the address field.
| Protocol | Check first | Common misdiagnosis |
|---|---|---|
| Shadowsocks | Address, port, password, encryption method, and any additional parameters required by the original configuration | The port may be reachable, but a mismatched password or encryption method can still prevent proxy requests from working. |
| VMess | UUID, encryption settings, transport method, and the corresponding TLS and transport parameters | A valid UUID does not confirm that the WebSocket path or Host is correct. Check the system time as well. |
| VLESS | UUID, transport method, and the TLS, REALITY, or Flow parameters used in the original configuration | Do not copy security settings from another server into the current configuration. |
| Trojan | Password, TLS, Server Name, and certificate verification | The address may connect, but a certificate name or authentication mismatch can still prevent the request from completing. |
| Hysteria2 | Authentication, TLS, port, and UDP reachability | It uses QUIC, so a successful TCP port probe does not prove that the connection works. |
| WireGuard | Keys, Peer, Endpoint, Allowed IPs, and tunnel address | Check UDP traffic and the handshake; a TCP probe alone cannot determine whether it works. |
Refreshing a subscription syncs configuration published by your provider; it does not fix every connection error. Confirm that the subscription is still valid, then refresh the corresponding subscription on Home and check whether the selected entry is still the one that failed. Keep a record before editing entries generated by a subscription, as a later refresh may overwrite your changes. Do not add the same subscription repeatedly as a troubleshooting step.
4. Check TLS, Server Name, and system time
TLS verification checks the server certificate and connection identity, including the certificate name, validity period, and trust chain. Server Name is generally used for TLS Server Name Indication and name verification; use the value specified in your existing configuration. It is not interchangeable with the WebSocket Host. Keep certificate verification enabled; skipping verification is not a routine fix.
System time affects certificate validity checks and may also affect authentication for some protocols. On iPhone or iPad, check automatic time settings and the current time under Settings → General → Date & Time. If device management policies restrict these settings, check the applicable requirements first. After correcting the time, reconnect; there is no need to change the protocol or DNS at the same time.
If the device time is correct but the certificate is still expired or its name does not match, ask your provider to verify the certificate and Server Name. Changing a domain address to an IP address does not automatically fix a certificate issue. If connecting by IP, the original Server Name may still need to be retained.
- Check the system date, time, and time zone. Make sure a manual setting has not caused a significant discrepancy.
- Check that TLS and Server Name in the server's edit screen match the original configuration. Do not reuse values from another entry.
- For WebSocket, check Host and the path separately. Match the server's capitalization and leading slash exactly.
- Reconnect and check the latest error. Note whether it has changed from a TLS error to an authentication error or a destination request error.
5. Check DNS and Global Routing separately
DNS resolves domain names to addresses and may affect both proxy server address resolution and destination website lookups. Default DNS behavior depends on the current Config and app settings. Keep the original configuration unless the logs show a resolution error. Adding multiple DNS addresses at random increases the number of variables and does not prove that the timeout has been resolved.
Global Routing determines how requests are routed. Proxy can temporarily test the currently selected proxy route, Direct connects directly, Config follows the active configuration rules, and Scene applies the configured scene. Check the current setting on Home. If switching briefly to Proxy restores access, check the policies or rules in Config; this does not prove that all DNS and protocol settings are correct.
- Server domain name fails to resolve: First verify the local network with a direct connection. Check the current DNS settings and any query errors in the logs, then ask your provider whether the address is still valid.
- Only some websites fail: Check the current setting under Home → Global Routing, then review the matching rules and policy targets in the file selected under Config.
- Config fails, but Proxy works: Check the rule order first.
DOMAIN-SUFFIX,IP-CIDR, andGEOIPcan produce different matches. PlaceFINALat the end of the rules as the final policy. - Failure starts only after switching scenes: Check the conditions for the selected Scene and the policy it uses. Do not rely only on the server name shown on Home.
After troubleshooting, restore the original Global Routing setting and retest with the actual destination. A temporary Proxy setting is only a comparison; it does not replace checking the DIRECT, PROXY, and REJECT policies in Config. If a rule explicitly rejects a request, switching servers will not change that result.
6. Narrow down the issue using log errors
Logs can help identify where a request fails. Open Settings → Log and check the relevant entries; logging options and detail levels depend on what the app currently displays. Enable only the logging needed while reproducing the issue. Note the time, then make one request to avoid mistaking old entries for current results. The error snippets below may be returned by the network stack; they are not fixed dialog messages, and the actual text may include additional prefixes or suffixes.
Error: i/o timeout
Cause and next steps: The connection or read/write operation did not finish in time. This message alone cannot distinguish packet loss, blocking, or an unresponsive server. Use the log stage to check the address and port, then retest the same configuration on another network.
Error: connection refused
Cause and next steps: The destination or an intermediary explicitly refused the connection. The port may not be listening, or a policy may be rejecting the connection. Check the port and protocol, and ask your provider to confirm that the service is running.
Error: no such host
Cause and next steps: Name resolution did not return a usable result. The address may be mistyped, or there may be a problem with the resolution path. Check the server address, then review the DNS settings and resolution results on the current network.
Error: certificate has expired or is not yet valid
Cause and next steps: The certificate validity period does not match the current time. Check automatic system time first. If the time is correct and the error persists, ask your provider to check the certificate rather than bypassing the issue by disabling verification.
An error changing from “resolution failed” to “authentication failed” means the request reached a different stage; it does not necessarily mean the issue is worse. Record each change and the new failure stage. If the connection fails only after a long idle period, note app backgrounding, network changes, and what happens after reconnecting. Then check automatic connection settings such as On Demand instead of increasing every timeout value.
7. Retest and prepare the details to share
A useful retest repeats the same destination with the same configuration under clearly stated network conditions. Keep at least one record of the failure and one comparison, noting whether the connection was enabled, the Global Routing setting, and the stage where the error occurred. Do not judge long-term reliability by a single latency reading or share an unredacted full configuration.
Why does the latency test show a result if the site still won't load?
First check the probe method under Home → Connectivity Test, then try to access the same destination. If only the TCP probe succeeds, check protocol authentication, TLS, and the policy in Config. A latency reading does not mean the full request succeeded.
Wi-Fi times out, but cellular works. Should I change the password?
Keep the password and protocol settings unchanged while recording the results on both networks. Check Wi-Fi sign-in, DNS, and UDP reachability. In particular, if you use Hysteria2 or WireGuard, ask the network administrator to check for UDP restrictions.
Still can't connect after refreshing the subscription. What should I do next?
On Home, confirm that the updated, valid entry is selected, then check its address, port, and protocol. If only one entry continues to fail, share the time, network type, and a redacted error with your provider for review. Do not repeatedly add the same subscription.
What should I hide when sharing troubleshooting details?
Include the protocol name, network type, exact error text, and reproduction steps. Hide passwords, UUIDs, keys, the full subscription URL, and any tokens in it. Before sharing logs, also check whether server addresses or visited domains reveal personal information.
- Local checks complete: Direct access works, the system time is correct, and Wi-Fi and cellular have been compared.
- Configuration checked: The address, port, authentication, TLS, and transport settings match the existing service configuration; values from other entries were not mixed in.
- Issue can be reproduced: Provide the time, failure stage, routing mode, and redacted logs—not just “it won't connect.”
- Settings restored: Restore On Demand, Global Routing, and any temporary logging options after troubleshooting, then verify normal access.