Use this guide to troubleshoot timeouts, handshake failures, and connection issues with existing entries in Shadowrocket. You’ll need your own service provider and subscription. Check the underlying network, test type, server settings, system time, and routing one at a time, then retest the same destination. Menu instructions below refer to the iPhone / iPad interface; system permissions and menu locations may differ on other platforms.
1. Identify where the timeout occurs
A timeout in Home does not necessarily mean the server is offline. A request may pass through the system tunnel, rule matching, address resolution, proxy connection, and destination response. A delay at any stage can cause it to fail. First note whether the test failed or the webpage itself failed; don’t delete all your settings right away.
On the same device, pause the Shadowrocket connection and try a website that normally opens directly. If that fails too, check Wi-Fi sign-in, mobile data permissions, or the network itself. Repeatedly switching servers won’t usually help if you haven’t completed the captive portal sign-in on public Wi-Fi.
- All entries fail: First check the current network, system time, subscription status, and any DNS issues affecting multiple entries.
- Only one entry fails: Check its address, port, and protocol settings, then ask your service provider to confirm the status of that service.
- The test returns a value, but the website won’t load: Check Global Routing, the action matched by the request, DNS, and the destination site. A latency result alone does not prove the connection works end to end.
- Works in the foreground but fails after switching networks: Note the differences between Wi-Fi and mobile data, and check whether automatic connection conditions in Settings → On Demand affect the retest.
2. Test latency and access under consistent conditions
Different tests check different things. A TCP connection test usually only shows whether a connection can be made to the specified address and port. It does not confirm valid credentials, a successful TLS handshake, or access to a webpage. Interpret Connectivity Test in Home according to the selected test type and destination; results from different test types aren’t directly comparable.
-
Record the current state
Note the entry name, test type, Global Routing mode, and time of failure. Keep a copy of the current configuration in Config. Hide credentials and subscription URLs in any screenshots or notes you share.
-
Select one entry
Choose an existing entry in Home so an automatic selection policy doesn’t switch the outbound connection during testing. Note whether you’re on Wi-Fi or mobile data.
-
Repeat the test
Run the same Connectivity Test three times and record each result and the reported duration. Don’t assume the issue is fixed because one test happened to succeed.
-
Test the destination
Turn on the connection and open the same known-good HTTPS page in a browser. Record test results separately from whether the page actually loads.
-
Switch networks
Keep the entry and destination the same, switch between Wi-Fi and mobile data, and repeat the tests. Be aware that mobile data charges may apply.
Takeaway: Determine whether the network or the entry is the difference
If the same entry fails on only one network, check that network’s DNS and transport restrictions. If the same entry fails on multiple networks while others work, check its address, port, and protocol settings instead of changing settings at random.
3. Check the address, port, and protocol settings
In Home, open the entry’s edit screen and compare each field with the original settings from your service provider. The server address should be a hostname or IP address, without a webpage path, spaces, or a protocol prefix. Use the specific port provided by your service provider. For example, if they specify port 443, don’t change it to 8443 just because that port appears in common examples. A port number alone does not identify the protocol.
| Protocol or layer | What to check | Commonly missed differences |
|---|---|---|
| Shadowsocks | Address, port, Password, encryption method | The encryption method must match the server. A correct password won’t compensate for a mismatched method. |
| VMess / VLESS | UUID, transport, TLS, and any server-specified options | Don’t copy only the UUID. Enter fields such as the WebSocket path and Host as specified in the original settings. |
| Trojan | Password、TLS、Server Name | The connection address may differ from the name on the certificate. Keep the name required by the server. |
| Hysteria2 | Authentication details, TLS, server-specified port, and additional settings | Uses UDP transport; a TCP port probe cannot replace a test using the actual protocol. |
| WireGuard | Key, Peer public key, Endpoint, tunnel address, and routing range | Check the handshake and data transfer. These settings can’t be diagnosed using the fields for password-based proxies. |
For TLS connections, distinguish between the server address, Server Name, and HTTP Host. They belong to different layers and shouldn’t be substituted for one another just because they look like domain names. WebSocket paths may also be case-sensitive; a missing leading slash or extra spaces can cause a failure.
4. Narrow down the cause from the exact error, then check system time
Log messages can help pinpoint the issue more precisely than “it won’t connect.” These are examples of underlying errors; capitalization, prefixes, and exact wording may vary by platform and connection stage. Use the logs recorded on your device as the source of truth. Save the exact message from the failure instead of labeling every error a server timeout.
Error: i/o timeout
Cause and fix: A network read or write did not complete within the time limit. This message alone doesn’t identify where it stalled. Check the surrounding log entries to see whether the issue occurred during resolution, connection, or response reading, then retest the same entry on another network.
Error: connection refused
Cause and fix: The connection was explicitly refused, often because nothing is listening on the port or the device rejected the request. Check the address and port, then ask your service provider to confirm the service status on that port.
Error: TLS handshake timeout
Cause and fix: The TLS handshake did not complete in time, possibly because the connection was blocked or the server did not respond. Check the TLS setting, Server Name, and port, then test on another network to see if the issue is network-related.
Error: certificate has expired or is not yet valid
Cause and fix: The certificate’s validity period doesn’t match the device’s system time. Correct the device clock first. If the error persists, ask the server administrator to check the certificate’s validity period.
On iPhone / iPad, go to Settings → General → Date & Time and check that Set Automatically is enabled and the date, time zone, and time are correct. On Windows, Mac, Android, and Linux, use the system’s date and time settings to synchronize the clock. Reconnect after correcting it and check whether the same error appears.
- An inaccurate clock can affect TLS certificate time checks and protocol authentication that relies on time windows.
- Correct system time does not guarantee a valid certificate. Expiration, name mismatches, and certificate chain issues must still be checked separately.
- If a certificate error occurs on only one destination website, first determine whether the proxy handshake failed or the destination website’s certificate caused the error.
5. After connecting, check routing, DNS, and subscription status
Turning on the connection means the system tunnel is active; it does not mean every request uses the selected proxy. Go to Home → Global Routing and check the current mode: Proxy routes traffic through the proxy, Direct connects without it, Config applies rules from the current configuration, and Scene uses its scene settings. For troubleshooting, temporarily select Proxy and retest the same destination, then restore the original mode.
- Proxy works, but Config doesn’t: Check the rule order and which rule actually matches in Config.
DOMAIN-SUFFIXmatches domain suffixes,IP-CIDRmatches address ranges,GEOIPmatches by IP geolocation, andFINALhandles connections not matched by earlier rules. - Matched DIRECT: The request did not use the proxy as expected. Check whether an earlier rule matched before changing the server password.
- Matched REJECT: A rule blocked the request. Check the rule’s purpose and scope; this does not mean the server failed to respond.
- Logs show a resolution failure: Check the DNS settings in the configuration, the spelling of the server hostname, and whether the current network can resolve it. Don’t casually replace the server hostname with an IP address; this could break TLS name matching or connect to the wrong address.
Subscription updates use a separate request path. A successful update only confirms that the subscription content could be downloaded and parsed; it doesn’t prove that every entry works. Likewise, a working entry doesn’t guarantee that the subscription URL is still valid. If your service provider changed the settings, update the relevant subscription in Home first, then check whether the entry actually changed.
Takeaway: Track update failures and connection failures separately
Record four things: subscription update result, selected entry, Global Routing mode, and actual access result. Check Update via Proxy in Settings → Subscribe only if the update request is blocked and you already have a working proxy. A proxy that cannot connect cannot provide a route for the update request.
To prevent automatic connection from interfering with the retest, note the current settings in Settings → On Demand and temporarily disable them if needed, then connect manually. Restore the original settings after testing; don’t leave a temporary troubleshooting mode as your everyday setup.
6. Common questions and what to include in a report
Why won’t a webpage load when latency is only a few dozen milliseconds?
First confirm which test produced that result. A fast TCP connection does not mean protocol authentication or access to the destination succeeded. In Home, check the selected entry and Global Routing mode, then open the same HTTPS page. Use the logs to distinguish a handshake error from a routing issue.
Wi-Fi times out, but mobile data works. Should I import the subscription again?
Don’t delete the subscription yet. Keep the same entry and protocol settings, then check whether Wi-Fi sign-in is complete and DNS resolution works. If you use Hysteria2 or WireGuard, also consider whether the network restricts UDP. Ask your service provider or network administrator to investigate the difference between networks.
One entry still times out after updating the subscription. What should I do?
Confirm that the entry’s settings actually changed, then compare its address, port, and authentication fields with the original settings. If other entries work on the same network, give your service provider the entry’s redacted name, failure time, and exact error message so they can check that service.
Do I need to send someone my full configuration for troubleshooting?
Usually, it’s enough to provide your system platform, protocol, network type, Global Routing mode, test type, and a redacted error message. Don’t share a full subscription URL, Password, UUID, private key, or QR code containing authentication details. Check logs for domains and personal information before sharing them.
After troubleshooting, retest with the original network, entry, and destination, and restore any settings you changed temporarily. If the issue persists, describe the steps to reproduce it: which network, which redacted entry, which routing mode, and the exact error. This is more useful than a timeout screenshot alone.