This article is for Shadowrocket users who already have Hysteria2 parameters from their service provider and want to understand connection behavior and complete a manual setup. It covers QUIC handshakes and packet-loss recovery, network suitability, Add Server field checks, Global Routing, and a troubleshooting order for failed connections.
How Hysteria2, UDP, and QUIC fit together
Hysteria2 in Shadowrocket is a proxy protocol built on QUIC. UDP provides the transport foundation for QUIC datagrams, while QUIC handles connection establishment, encryption, congestion control, acknowledgements, and packet-loss recovery in user space. Hysteria2 should not be reduced to “sending UDP directly”: application data first enters a Hysteria2 session, then QUIC organizes it into encrypted, numbered packets.
A traditional TCP-encrypted connection usually completes a TCP handshake followed by a TLS handshake. On a link with a round-trip time (RTT) of 180 ms, each additional round trip that waits for a reply adds about 180 ms before the first useful data can arrive. QUIC combines transport connection setup with TLS 1.3 negotiation, so a new connection can usually become ready for data with fewer round trips. Actual timing still depends on DNS resolution, server response time, wireless scheduling, and network congestion; it does not always save a fixed number of milliseconds.
QUIC also supports multiple logical streams. When a packet is lost, the stream that needs its contents waits for retransmission, while other streams that do not depend on that packet can continue. This reduces head-of-line blocking between streams. For continuous data carried in a single stream, missing bytes still need to be recovered, so using QUIC does not make packet loss irrelevant.
- UDP: Carries datagrams but does not itself guarantee ordering, retransmission, or delivery.
- QUIC: Implements encrypted connections, acknowledgements, retransmission, congestion control, and multiple streams over UDP.
- Hysteria2: Uses QUIC to establish a session between the client and server, then carries proxy traffic through that session.
- Shadowrocket: Reads Address, Port, Password, SNI, and other settings, starts the Hysteria2 connection, and makes it available to Global Routing.
Why it can be faster on high-latency, lossy links
The speed difference mainly comes from congestion control and packet-loss recovery, not from the protocol name itself. When packets are lost, the sender must determine what failed to arrive, schedule retransmissions, and adjust its sending rate. The higher the RTT, the more costly incorrect decisions or acknowledgement waits become; sustained loss makes usable throughput fall more easily. QUIC maintains acknowledgement ranges and loss timers in user space, allowing implementation strategies to evolve quickly, but actual throughput remains limited by the server's egress, device performance, and access network.
A Hysteria2 configuration may include upstream and downstream bandwidth values. These are not speed-test results, and higher is not always better. Some implementations choose different congestion-control behavior depending on whether bandwidth parameters are provided. If your service provider gives specific values, enter them as provided; if they say to leave them blank, do not fill them in based on your broadband plan's advertised speed. Entering 500 Mbps for a link that actually delivers 50 Mbps can cause excessive sending, queue buildup, higher latency, or more packet loss.
The bandwidth-delay product provides a useful example: on a 100 Mbps link with a 200 ms RTT, about 2.5 MB of data can be in flight, calculated as 100,000,000 bit/s × 0.2 s ÷ 8. If the sending window is much smaller, the link may not be fully utilized; if data is sent too quickly for the intermediate queues, queuing and packet loss can occur. Hysteria2's performance depends on whether congestion control can approach the link's actual capacity.
Use the original parameters
RecommendedUse the user's existing configuration for Address, Port, Password, SNI, bandwidth, and verification options. Do not guess missing values.
Suitable for: initial setup and everyday use
Leave optional fields blank
If the service provider specifies the default congestion control or does not request bandwidth values, leave the corresponding optional fields blank.
Suitable for: configurations with an explicit default value
Increase the bandwidth values yourself
Entering values above the actual access capacity can worsen queuing; it cannot be used to determine whether the protocol itself is working correctly.
Suitable for: parameter testing on controlled networks only
Conclusion: identify the bottleneck before adjusting parameters
If Connectivity Test latency is stable but large transfers fluctuate, first verify the bandwidth fields supplied by the service provider and UDP reachability. Do not repeatedly increase Up, Down, or similarly named fields based on a single speed result.
Which networks suit Hysteria2
Hysteria2 is often used on links with higher RTT, random packet loss, or frequent network changes. Changing mobile signal conditions, long-distance paths, and congested periods can all make traditional reliable transport wait longer for recovery. QUIC can recover lost packets and keep multiple streams moving when network conditions allow, so these environments make differences in connection setup and sustained transfers easier to observe.
On a stable path with low latency and little packet loss, every protocol may be limited by the server's egress or access bandwidth, so Hysteria2 may not deliver a noticeable speed difference. If the current network restricts UDP, the QUIC handshake may time out directly, while an existing configuration using another transport may still connect. Choose a protocol based first on reachability and parameter compatibility, not theoretical throughput alone.
| Observed behavior | Possible meaning | Recommended action |
|---|---|---|
| RTT of 150–250 ms with occasional 1%–3% packet loss | Variation on a long-distance or wireless link | Test Hysteria2 with the original parameters and record several Connectivity Test results |
| Latency is steady but rises noticeably during transfers | Queue congestion or bandwidth values set too high | Restore the Up and Down values provided by the service provider; do not inflate them to match advertised bandwidth |
| Always shows timeout | UDP is unreachable, Port is incorrect, or handshake fields do not match | Retest on a network known to allow UDP, then verify Port, SNI, and Password |
| Only some domains fail after connecting | A rule or DNS path issue may be involved | Check Global Routing and use Proxy briefly for comparison |
Conclusion: check UDP reachability first when you see timeout
If the same parameters connect on one network but continuously show timeout on another, first check whether the current network can reach UDP and the target Port. If every network fails, return to checking the fields.
Manually configure Hysteria2 in Shadowrocket
Before starting, prepare the complete parameters provided by your service provider. These usually include the server Address, Port, and authentication details; TLS setups may also include SNI. Some configurations additionally specify ALPN, an obfuscation password, upstream or downstream bandwidth, and certificate-verification options. Field names may vary by interface and configuration method, but parameter meanings must not be mixed up.
Port 443 is a common example, not a requirement for every Hysteria2 service. Enter the hostname or IP in Address, and make Port match the server's listening port. Password is the Hysteria2 authentication value, not Shadowrocket purchase credentials. SNI is the server name checked during the TLS handshake and should normally remain the domain supplied by the service provider.
Verify the app
Get Shadowrocket from the App Store and verify the developer, Shadow Launch Technology Limited, and app ID 932747118. The app is sold as a one-time purchase; check the App Store product page for system requirements.
Open the add-server screen
In Home, tap “+” in the upper-right corner to open Add Server, then choose Hysteria2 under Type.
Enter the connection fields
Enter Address, Port, Password, and SNI in order. Fill optional fields such as ALPN, Obfuscation, Up, and Down only when they are explicitly included in the existing configuration.
Check verification options
Follow the existing configuration for certificate-verification switches. Keep verification enabled for a normal certificate setup; do not change verification merely to work around incorrect fields.
Save and select it
After saving, return to Home and tap the new server entry. Confirm that the selection indicator appears beside it.
Run a connection test
Turn on the connection switch and authorize the system VPN configuration, then run Connectivity Test. If it fails, record whether the message indicates timeout, TLS, or authentication.
If your service provider delivers a single Hysteria2 URI, first verify its structure, then use an import entry supported by Shadowrocket. The example below uses placeholder syntax and cannot establish a real connection. The authentication value, hostname, Port, query parameters, and name fragment in a URI each serve different purposes; Password values containing special characters must also be URL-encoded correctly.
hysteria2://[email protected]:443/?sni=edge.example.com&insecure=0#HY2-demoIf you already have a subscription, tap “+” in the upper-right corner of Home, open Add Server, set Type to Subscribe, and enter the subscription URL. The example value is https://example.com/sub?token=xxxx. After saving, return to Home and pull down to update. Subscription updates may overwrite or rebuild entries managed by that subscription. Before changing parameters, confirm whether the service provider requires changes in the subscription source instead of manually editing an automatically generated server record.
How Global Routing and On Demand work together
Hysteria2 determines how the client and server establish a transport session; Global Routing determines which requests use that session. They operate at different layers. After selecting a Hysteria2 entry in Home, traffic is still handled as direct traffic if Global Routing is set to Direct. Seeing a server selected does not by itself prove that requests are using the connection.
Config matches traffic against the rules in the current configuration file. Common rule keywords include DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL. Rules are usually evaluated from top to bottom; the first matching rule determines the action, while FINAL handles requests that matched nothing earlier. Proxy can serve as a temporary comparison when troubleshooting rules, Direct can help determine whether an issue is related to the proxy path, and Scene switches preset behavior according to scenario conditions.
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
IP-CIDR,192.0.2.0/24,PROXY,no-resolve
FINAL,PROXY- Proxy: Uses the currently selected server for traffic, which is useful for briefly checking whether rules are leaving traffic unproxied.
- Direct: Connects traffic directly, which is useful for comparing behavior with the proxy path.
- Config: Matches traffic against the configuration file rules one by one, which suits everyday routing.
- Scene: Selects behavior based on configured network conditions; verify the scene conditions before using it.
On Demand triggers connections according to conditions. Go to Settings → On Demand → Enable, then configure trigger rules for your network. When troubleshooting Hysteria2 for the first time, keep the process simple: select the server manually, turn on the connection manually, and run Connectivity Test. Enable On Demand only after the basic connection works. Otherwise, trigger conditions, system VPN state, and protocol parameters can all affect the result at once, making the source of a failure difficult to identify.
In the rule syntax examples, example.com and 192.0.2.0/24 are for illustration only. Actual Config should use rules maintained by the user or supplied by an existing configuration. Preserve the original configuration before editing, then test requests matching Proxy, Direct, and FINAL separately instead of judging the entire rule set from a single webpage.
Troubleshooting order for timeouts, handshake failures, and fluctuating speeds
Start with the conditions that are easiest to verify. Confirm that the device time is set automatically, then check Address and Port, followed by Password, SNI, ALPN, and obfuscation parameters. Adjust bandwidth and routing only afterward. An incorrect device clock can affect TLS certificate validity checks; an incorrect Address or Port usually causes continuous timeout; a mismatched Password may cause authentication failure; and an SNI that does not match the certificate name may trigger a TLS error.
Connectivity Test is useful for checking the selected entry's latency and basic reachability, but one result does not represent sustained throughput. Run three to five tests in succession and record whether all time out, whether only the first is slow, and whether latency jumps from 80 ms to 600 ms. If the test passes but actual requests fail, check Global Routing, Config rules, and DNS handling instead of continuing to change the Hysteria2 Password or Port.
What if it always shows timeout?
First confirm that Home has the newly added Hysteria2 entry selected, then verify Address and Port. Next, retest on a network known to allow UDP. If the failure occurs only on one network, first assess that network's UDP reachability.
What should I change when a TLS error appears?
Check that the device time is set automatically and verify SNI character by character. SNI is usually a domain, not a remark or display name. Follow the existing configuration for certificate verification; changing verification options is not a substitute for entering the correct values.
Connected, but speed keeps fluctuating?
Run Connectivity Test three to five times and observe latency variation. Then check whether Up, Down, or similar bandwidth fields were increased manually. Restore the original values supplied by the service provider and test again; avoid changing multiple fields at once.
The server is selected, but traffic is not using it?
Check the Home connection switch and Global Routing. If the current mode is Direct, switch briefly to Proxy for comparison. If Proxy works but Config does not, return to Config and check rule order and the FINAL action.
Manual values disappeared after a subscription update?
Entries managed by Subscribe may be rebuilt from the subscription content during an update. First check the entry's source in Home, then ask your service provider to verify the Hysteria2 parameters in the subscription. Do not rely on temporary edits that an update will overwrite.
To distinguish a protocol issue from a rules issue, temporarily set Global Routing to Proxy, select the target Hysteria2 entry, and run Connectivity Test. After the basic connection works, restore Config and check DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL one by one. Restore the original routing mode when troubleshooting is complete; do not leave the test setting enabled long term.
Shadowrocket is primarily used on iPhone and iPad. For Mac, Apple TV, and Apple Vision availability, check the compatibility section on the App Store product page; system requirements are as listed there. Network switching and system VPN behavior may differ by device, but the Hysteria2 checking principles are the same: verify the address and port first, match authentication and TLS parameters one by one, then handle congestion control and rule routing.