Hysteria2’s potential advantages come from QUIC’s transport mechanisms and bandwidth-aware congestion control—not from any speed guarantee built into UDP. This guide is for users who already have server details or a subscription. It covers network conditions, authentication and TLS settings, setup in Shadowrocket, and how to distinguish UDP connectivity issues from certificate errors and routing-rule problems. Confirm that the connection works before evaluating throughput.
What Hysteria2, QUIC, and UDP each do
Hysteria2 in Shadowrocket is a proxy protocol option. It is built on QUIC, which carries packets over UDP. These terms are not interchangeable: UDP provides datagram transport; QUIC adds encryption, connection management, and reliable streams; Hysteria2 defines proxy authentication, request forwarding, and related transport behavior. The server must support the protocol. Changing the Type of an existing entry to Hysteria2 does not convert it.
UDP does not guarantee delivery or packet order, but that does not mean web pages accessed through Hysteria2 will arrive with missing content. QUIC streams handle acknowledgments and retransmissions for data that needs reliable delivery. Proxied UDP traffic can use datagrams, which have different semantics from a reliable byte stream. When evaluating performance, distinguish the outer transport from the connections used by the application inside it.
Use the port specified in your existing service details. A TCP port and a UDP port with the same number use different transport protocols: access to TCP 443 does not prove that UDP 443 is available. Opening a regular web page only confirms that the path used by that page works; it does not verify the Hysteria2 handshake.
Why high-latency, lossy connections may benefit
Network throughput depends not only on advertised bandwidth, but also on round-trip time, packet loss, the sending window, and congestion control. Traditional loss-based control may treat random packet loss caused by wireless interference as congestion and reduce the sending rate. Hysteria2’s congestion control aims to use link capacity more aggressively in these conditions. Whether it is used, and how well it works, also depends on the client, server, and negotiated bandwidth settings.
QUIC’s multiple streams reduce transport-layer head-of-line blocking between streams: when one stream waits for lost data to be retransmitted, a gap in its ordered byte stream does not automatically block every other stream. Packet loss still occurs, however. A reliable stream must still wait for missing data, and all streams share link capacity and congestion. Using QUIC does not mean every network will be faster.
- High latency with random packet loss: If UDP is reachable and the server has sufficient resources, a more aggressive sending strategy may improve sustained throughput.
- Low latency with little packet loss: The bottleneck may already be the access link, server egress, or destination site, so switching protocols may make no noticeable difference.
- Actual network congestion: Sending more data may increase queuing, jitter, and packet loss. Not all loss can be attributed to wireless interference.
- UDP blocked or rate-limited: You may see handshake timeouts or restricted throughput after connecting. Protocol mechanisms cannot remove path limitations.
Bottom line: Check UDP reachability before adjusting bandwidth
If the connection remains stuck during the handshake, first check the server address, UDP port, and network you are using. Raising the bandwidth setting will not fix a reachability problem. Compare throughput and latency only after the connection is stable.
Before entering settings, distinguish the address, authentication, and TLS fields
A Hysteria2 entry needs at least a valid server address, port, and authentication details. TLS identity verification, obfuscation, and bandwidth options must match the service configuration you already have. Use subscription parameters as a reference rather than overwriting everything based on assumptions. In particular, the server address, certificate name, and authentication password are separate fields.
| Setting | What to enter and check | Common misinterpretation |
|---|---|---|
| Server address and Port | Enter the domain or IP address and corresponding UDP port from your existing details. Port numbers range from 1 to 65535. | Assuming every service uses 443, or treating TCP reachability as proof that UDP is reachable. |
| Authentication | Preserve capitalization and include every character. If the service requires a combined format, enter it exactly as provided. | Entering only part of combined credentials, or including spaces or line breaks when copying. |
| SNI and certificate | Enter the TLS name specified by the service and check how it relates to the certificate and connection destination. | Entering an IP address, seeing a name mismatch, and then disabling certificate verification. |
| Obfuscation | Set this only if the server requires it. For example, with Salamander, both ends must use the same type and password. | Adding obfuscation unnecessarily, or mistaking the obfuscation password for the authentication password. |
| Bandwidth | Use the actual available upload and download bandwidth and the values agreed for the service. Check the units shown in the interface. | Treating the value as a speed multiplier, or confusing Mbps with MB/s. |
For example, an existing configuration may use an IP address as the connection destination and a domain name as the TLS identity. In that case, the address field and SNI may correctly differ. Check the original settings rather than forcing them to match. If you see a certificate error, check the system clock, SNI, certificate validity, and service configuration. Keep certificate verification enabled instead of hiding the error by skipping verification.
Add a Hysteria2 entry in Shadowrocket and verify it
These steps assume you already have your own Hysteria2 settings. If you use an existing subscription, tap “+” in the upper-right corner of Home, set Type to Subscribe, enter your subscription URL, and save. After updating, check the generated entry’s Type and settings. A subscription fetch failure and a Hysteria2 handshake failure are different issues: the former occurs while retrieving configuration; the latter occurs when connecting with an entry.
-
Check your existing settings
Have the address, UDP port, and authentication details ready, along with any SNI, obfuscation, and bandwidth settings required by the service. Do not assume that settings for the older Hysteria protocol apply to Hysteria2.
-
Add an entry
On Home, tap “+” in the upper-right corner, open Type, and select Hysteria2. Enter the existing server address and Port, making sure no digits are missing or duplicated.
-
Enter authentication details
Copy the complete authentication details and configure obfuscation as specified in the original settings. Check the authentication and obfuscation passwords separately; do not assume they should be the same just because both fields request a password.
-
Check TLS
Check the SNI and certificate verification settings. Enter bandwidth values using the units shown in the interface. If an existing subscription already sets these values, leave them unchanged for the first test so you do not change several variables at once.
-
Save and test
After saving, return to Home, select the entry, check Global Routing, and connect. The first time you connect, follow the system prompt to allow a VPN configuration. Then verify the connection with an actual web request rather than relying only on a latency reading.
Updating a subscription may change entries generated from it. To avoid confusion, note the current settings and any subscription update time shown before testing. If you make manual changes, check them again after an update. When sharing troubleshooting details, hide authentication data and subscription tokens. Share the error type, network type, and port only; never post complete credentials publicly.
Choosing Global Routing for troubleshooting
Protocol connectivity, routing mode, and rule matching are separate layers. Selecting a Hysteria2 entry on Home does not mean every request will use it. Global Routing and policies in Config may still route requests through DIRECT or another policy. When troubleshooting an entry, first minimize the effect of rules, then restore your usual configuration.
Proxy: Isolate rule-related variables
RecommendedFor a brief troubleshooting test, use Proxy and confirm that the Hysteria2 entry you want to test is selected. This routes connections handled by the client through the proxy, reducing interference from Config rules. Keep separate settings such as local network exclusions in mind.
Best for: Verifying settings for the first time and separating protocol issues from rule issues
Config: Check your usual routing rules
After confirming the connection works, switch back to Config and check which rules and policies match the actual requests. Rules such as DOMAIN-SUFFIX, IP-CIDR, and GEOIP determine where traffic goes; FINAL applies the fallback policy when no earlier rule matches.
Best for: Existing rule configurations and routing traffic by destination
Direct: Check the direct-connection baseline
Direct helps you check whether direct access works; it does not verify that a Hysteria2 entry works. If a web page opens in this mode, it only shows that the corresponding direct request succeeded. It does not prove that a proxy handshake completed.
Best for: Comparing direct access over your local network with access to the destination site
If a request works in Proxy but fails after switching back to Config, focus on the rule order and destination policy in Config rather than immediately changing the Hysteria2 password. Rules are matched from top to bottom, so an earlier broad rule may override a more specific rule below it. FINAL should be at the end of the rule list. Also check that the entry or policy group used by PROXY is the one selected during testing.
Common issues: Identify the stage, then change one variable at a time
An enabled connection toggle, a latency test result, and an accessible destination site indicate different things. The system VPN status does not mean every remote connection succeeds, and a single latency test does not show sustained transfer performance. Use the observations below to troubleshoot without assuming the protocol is at fault.
Wi-Fi keeps timing out, but cellular works?
Keep the same entry, port, and destination request; switch only the network and test again. If the difference is repeatable, check UDP reachability, rate limits, or firewall policies on the Wi-Fi path first. Do not change the password right away, since the same settings connected successfully over another path. Be mindful of cellular data usage.
Seeing a certificate or TLS error—should you disable verification?
First check the device clock, the entry’s SNI, and your existing service settings. Then confirm that the domain resolves to the expected address. A name mismatch or expired certificate requires correcting the relevant settings. Do not routinely disable certificate verification as a troubleshooting step, and do not assume every handshake timeout is a certificate error.
Small pages load, but large file transfers keep stalling?
First lower an overly high bandwidth setting, then repeat the same request on the same network. If the issue persists, note when it occurs and check the path MTU, UDP fragmentation, and rate limits. Do not change the MTU based on this symptom alone; also rule out limits on the server’s egress or at the destination site.
Manual connections work, but automatic connections behave unexpectedly?
In Settings → On Demand, check the toggle and configured network triggers. Confirm whether the current Wi-Fi or cellular connection meets the conditions. Use a manual connection when testing the protocol to avoid automatic disconnections or reconnections affecting your observations. Once the protocol and routing work, test On Demand separately.
For a performance comparison, keep the device, network, entry, destination resource, and test time consistent. Change only one setting per run. Record whether the handshake completes, when the first web response arrives, whether sustained transfers remain stable, and whether latency rises significantly under load. Do not use downloads from different destination sites to claim that one protocol is consistently faster by a particular amount.
- Verify first: Check that the address, UDP port, authentication, TLS, and obfuscation match your existing settings.
- Isolate next: Use a manual connection and an explicit Global Routing mode to rule out automation and rule-related interference.
- Compare last: Under repeatable conditions, check throughput and jitter to see whether the change actually improves performance.