This guide is for users who already have their own service and subscription and want to use Hysteria2 in Shadowrocket. It explains how QUIC, UDP and congestion control work together, then walks through the address, port, authentication, TLS and bandwidth fields to check. Your network's UDP reachability, packet-loss patterns and sustained performance matter more than a single latency reading when deciding whether Hysteria2 is a good fit.
How Hysteria2, QUIC and UDP work together
Hysteria2 is a proxy protocol built on QUIC. Shadowrocket connects to your own Hysteria2 server, which then forwards traffic to its destination. Buying the app and using a connection service are separate: purchasing the client does not provide a server address, authentication details or a subscription.
UDP is the underlying transport. QUIC uses it to provide encryption, connection management, reliable streams and congestion control. “Built on UDP” does not mean lost data is ignored: QUIC's reliable streams still use acknowledgments and retransmissions for proxied TCP traffic, while proxied UDP traffic uses delivery semantics suited to datagrams.
443/UDP is just an example port. A server can listen on a different UDP port, and the client must use the actual port. A network allowing 443/TCP does not necessarily allow 443/UDP. Being able to open regular websites in a browser also does not prove that the Hysteria2 transport path is available.
Why it can be faster: multiplexing and congestion control
QUIC can carry multiple streams over a single connection. If one stream loses packets, other streams do not necessarily have to wait for a single outer TCP byte stream to fill in the missing data before delivering their own. However, all streams still share the link's capacity and congestion control, and each reliable stream still has its own in-order delivery requirements.
Another key Hysteria2 feature is Brutal, a bandwidth-driven congestion control algorithm. It sends at a configured target rate and compensates for packet loss. When loss is random and the link still has spare capacity, this approach may sustain throughput better than strategies that sharply reduce their rate in response to loss. Whether Brutal or a path such as BBR is used depends on bandwidth settings, negotiation and the client and server implementations; the protocol name alone does not tell you which one is in use.
| Mechanism | What it may improve | What it cannot overcome |
|---|---|---|
| QUIC multiplexing | Waiting between streams due to in-order delivery at the outer transport layer | All streams still compete for capacity on the same link |
| Reliable-stream retransmission | Restores data integrity for proxied TCP traffic after packet loss | Retransmissions take time and consume additional bandwidth |
| Brutal | Reduced sustained throughput under random packet loss | Setting the target bandwidth too high can increase queuing and packet loss |
| BBR congestion control | Adjusts sending behavior based on link estimates | Results depend on the path, implementation and server-side limits |
First estimate available capacity, then set bandwidth
Record sustained download and upload speeds and response latency on the same path, then set bandwidth based on its actual capacity. If raising the value does not improve throughput but makes web responses slower, lower it and test again instead of increasing it further.
Speed is not an inherent property of a protocol. High latency adds waiting time for handshakes, request round trips and packet-loss recovery; QUIC cannot eliminate physical distance. Server egress capacity, destination-site throttling and local wireless interference do not disappear when you switch protocols. This guide makes no untested percentage claims about speed improvements.
Network conditions that may suit Hysteria2—and those to rule out first
Hysteria2 is worth testing first when UDP is reachable, the link has relatively high latency and some random packet loss, and there is still bandwidth available. If packet loss is caused by a persistently full queue, sending faster may make things worse. Distinguish random loss from congestion-related loss; a single packet-loss percentage is not enough to decide.
- Long-distance links: Check whether sustained transfers remain stable and record web response times. Fast large downloads do not necessarily mean responsive browsing.
- Unstable Wi-Fi: Test closer to the access point and pause other high-bandwidth activity first, so local wireless interference is not mistaken for a protocol issue.
- Networks that restrict UDP: If the handshake consistently times out, check the UDP port and network policy first. Raising the bandwidth setting cannot fix an unreachable path.
- Persistent congestion: If latency rises sharply during transfers and recovers as soon as they stop, lower the bandwidth target and check how much capacity other devices are using.
- Short-distance links with little packet loss: Switching protocols may offer little benefit. Consider stability, server support and the tasks you actually need to perform.
Add Hysteria2 in Shadowrocket: fields to check
When available, use the complete configuration from a subscription you already have to avoid missing TLS or authentication parameters. Hysteria2 and the older Hysteria protocol are not interchangeable by simply changing the name. After importing a configuration, open the entry and confirm that Type is set to Hysteria2. Field order may vary with the app's language and version, so check what each field means instead of guessing from similar labels.
-
Confirm the source
Have the address, UDP port, authentication details, TLS settings and any optional obfuscation parameters for your own service ready. To import a subscription, go to Home → tap “+” in the top-right corner → Type → Subscribe, then enter your own subscription URL and save.
-
Choose the protocol
To add a server manually, go to Home → tap “+” in the top-right corner → Type → Hysteria2. For an imported subscription, open the relevant entry and check Type. Do not switch it to a different protocol and keep using the original parameters.
-
Enter connection details
Enter the address and port provided by your server, then add the authentication details. Put only the hostname or IP address in the address field; do not include a web page path, protocol prefix or port. Enter the port separately—for example, use 443 if that is the port specified by the server.
-
Check encryption settings
Check the TLS server name (SNI) and certificate requirements. If the server uses obfuscation, match the obfuscation type and password as well. The authentication password and obfuscation password serve different purposes and cannot be used interchangeably.
-
Save and test
After saving, return to Home, select the entry and connect. Note your current Global Routing setting and test against a destination you know is reachable. Restore your usual settings afterward; do not change DNS, rules and bandwidth all at once.
| What the field means | How to choose a value | Common mistake |
|---|---|---|
| Server address | Hostname or IP address provided by the server | Entering a web admin page address or subscription URL |
| Port | UDP port the server is actually listening on | Using a TCP port for a different service |
| Authentication | The complete authentication string specified by the server | Truncating the value or adding leading or trailing spaces |
| SNI | Server name on the TLS certificate | Assuming the certificate name does not need checking when connecting by IP |
| Obfuscation settings | Whether the server uses obfuscation and the corresponding parameters | Enabling it only on the client, or using a different password |
| Upload and download bandwidth | Link capacity in the client-to-server direction and server-side limits | Reversing upload and download values, or entering MB/s as though it were Mbps |
Pay close attention to bandwidth units: 1 MB/s = 8 Mbps. Actual payload throughput is also affected by transport overhead. Download usually means traffic from the server to the client, and upload means the reverse; follow the current field descriptions. A high advertised speed on your local connection does not mean the remote path can sustain the same rate.
After connecting: confirm traffic is using the selected entry
Selecting a Hysteria2 entry in Home does not mean every request goes through it. In Global Routing, Direct means traffic connects directly; Proxy is used to test proxy routing; Config applies the rules in the active configuration file; and Scene requires checking the settings for the active scene. Record the routing mode during diagnosis, or protocol comparisons may end up testing different paths.
When using Config, open Config to confirm which file is active, then check which rule matches the request. Rules are usually evaluated in order. The examples below explain syntax only; they are not a complete configuration to replace your existing file. The PROXY policy must exist in your actual configuration and point to the intended route.
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXYDOMAIN-SUFFIXmatches domain suffixes. First check whether the test domain matches a rule of this type.IP-CIDRmatches an IP range. In this example,no-resolveprevents an extra domain lookup for this rule.GEOIPmatches IP geolocation data; results depend on the resolved IP and the data source in use.FINALhandles requests that match none of the preceding rules. Do not check it in isolation while ignoring earlier rules.
If the connection restores itself during testing, check the existing settings under Settings → On Demand to see whether an automatic connection was triggered. On Demand controls when a connection starts; it does not fix incorrect authentication, port or TLS settings. Note the original settings before making temporary changes, then restore them when troubleshooting is complete.
Hysteria2 troubleshooting: diagnose by symptom
Why does the connection keep timing out when regular websites still load?
First check that the address resolves correctly and that the server is using the expected UDP port. Then, if available, try connecting to the same entry over another network. Regular websites may use TCP, which does not prove the UDP path is working. If the connection fails on only one network, check that network's UDP policy first. If it fails on both, check the server's listening port, firewall and service status.
Why am I seeing an authentication or certificate error?
For an authentication error, compare the complete string and check for leading or trailing spaces. Do not use the subscription URL as the password. For a certificate error, check the device clock, SNI and server certificate; even when connecting by IP, you may still need to enter the domain name on the certificate. A mismatch in obfuscation settings can also cause a handshake failure, so compare each parameter with the server settings.
Why does performance get worse when I set a higher bandwidth?
If the target rate exceeds the path's capacity, queuing, retransmissions and compensation traffic can increase. Lower the bandwidth target, pause other high-bandwidth activity and compare web response times during sustained transfers. If throughput does not improve but response latency increases, keep the lower setting and check whether the server limits the available rate.
Why can I connect but still not open some websites?
First check Global Routing in Home and rule out Direct or rules that send traffic through a different path. Then check the matching rules in Config and DNS resolution. If only large responses or certain networks fail, check the path MTU, UDP fragmentation and intermediate network restrictions. Do not change DNS, ports and obfuscation settings all at once before identifying the cause.
Why did my manual changes disappear after a subscription update?
A subscription update may overwrite entries managed by that subscription. Record your changes first, then check whether the subscription already provides the correct settings. For long-term use, rely on valid details for your own service. Subscription updates, Config updates and app updates from the App Store are separate operations and cannot replace one another.
When keeping a final configuration, record at least the network type, server entry, Global Routing mode, bandwidth settings and the exact steps that trigger the issue. Repeated results from the same task are more useful than a single peak-speed reading. If the issue occurs only with a particular server, share a redacted description of the problem with your service provider. Never disclose authentication details.