This guide is for users who already have a configuration from their service provider and want to use Hysteria2 in Shadowrocket. First, distinguish QUIC and UDP from the traffic they carry. Then check the authentication, certificate, and obfuscation settings, and test the connection under consistent conditions. By the end, you’ll be better able to tell whether a problem lies with network reachability, TLS, authentication, or routing rules—rather than switching protocols based on a single latency test.
How Hysteria2 relates to QUIC and UDP
Hysteria2 is a proxy protocol built on QUIC. QUIC carries data over UDP and provides encryption, reliable delivery, congestion control, and multiplexing. “UDP-based” describes the underlying transport between the client and server. It does not mean web requests become unreliable, or that users can access only UDP-based services.
When you select Hysteria2 in Shadowrocket, TCP traffic routed through that connection can be forwarded over QUIC streams; UDP traffic uses the corresponding datagram forwarding mechanism. Web applications continue to use their usual protocols—you don’t need to switch your browser to HTTP/3. The server must support Hysteria2. Matching the address and password alone does not make a configuration for another protocol compatible with Hysteria2.
Using the same port number does not mean the transport is the same. For example, if the server listens on 443/UDP, allowing only 443/TCP on the network still won’t establish the connection. Port 443 is not required for Hysteria2. If you use 8443 or another port, the client setting, server listener, and firewall rule must all match.
Performance on unstable networks and the limits of congestion control
QUIC multiplexing reduces head-of-line blocking between streams caused by reliable, in-order delivery: if data in one stream needs retransmission, data already received by another stream doesn’t have to wait for the same TCP byte stream to be completed. However, all streams still share the path’s bandwidth and congestion control. Persistent packet loss, a weak wireless signal, or a congested uplink can affect all traffic.
Hysteria2 congestion control includes Brutal, which uses bandwidth estimates, and negotiable BBR. The method actually used depends on the client implementation, configuration, and server negotiation. Brutal needs a reasonable bandwidth setting and uses loss feedback to control sending. It cannot create bandwidth or bypass network restrictions on UDP.
- Random packet loss or latency fluctuations: Test an existing Hysteria2 configuration under consistent conditions. Compare page load times and long-lived connection stability rather than assuming it will be faster.
- UDP is dropped or heavily rate-limited: Common symptoms include repeated handshake timeouts or very low throughput after a transfer starts. Increasing the bandwidth setting usually won’t address the underlying cause.
- The uplink is saturated: Uploads can crowd out the space needed for acknowledgments and control packets, which may also slow downloads. Pause other uploads before testing.
- Limited server egress: Even with a good local connection, the destination’s response, remote server load, or server egress bandwidth may be the bottleneck.
First, confirm that UDP is reachable
If handshakes keep timing out, first check the address and UDP port in your existing configuration, along with restrictions on the current network. Bandwidth settings are worth investigating only after the connection can be established and sustain traffic.
What password, sni, and obfs control
These settings apply at different layers and are not interchangeable. Before adding a configuration, confirm all required values with your configuration provider. If a field is missing, don’t fill it in with a different password. The English terms below are configuration field names; Shadowrocket may display them as corresponding labels. Which fields appear depends on the selected Type and the actual interface.
| Setting | Purpose | What to check |
|---|---|---|
server | The domain name or IP address of the server you’re connecting to. | Don’t enter a full share link or a web address with a path in the address field. |
port | The server’s UDP listening port. | For example, 443. It must match your existing configuration; don’t change it to 443 just because websites use HTTPS. |
password | Credentials used to authenticate with the Hysteria2 server. | Preserve capitalization and symbols. Check that no spaces were copied at the beginning or end. |
sni | The server name used in the TLS handshake and checked against the certificate name. | Usually a domain name, without a scheme, port, or path. Use the value from your existing configuration. |
obfs | An optional transport obfuscation method, such as Salamander. | If enabled on the server, it must match on both ends. Don’t enable it on just one side. |
obfs-password | The key used for obfuscation. | This is separate from the authentication password. An incorrect obfuscation key can cause the handshake to fail. |
up / down | Upload and download bandwidth hints in some configuration formats. | Check the units and direction. Don’t treat a speed test result in MB/s as Mbps. |
The connection address and sni can be different. For example, an existing configuration may connect to an IP address while using a domain covered by the certificate for the TLS name check. This does not mean you can enter an arbitrary well-known website’s domain: the certificate chain, certificate name, and server configuration must match. If you see a certificate error, check sni, the device’s clock, and the server certificate status rather than disabling certificate verification.
Add and check a connection in Shadowrocket
These steps start from Home on iPhone or iPad and assume you already have a valid Hysteria2 configuration. If you already have a Subscribe entry, update it and check the import first. Adding a connection manually is useful for checking a single entry; avoid repeatedly overwriting entries managed through a subscription.
-
Check the configuration details
Have the server address, UDP port, password, sni, and any obfs details required by the server ready. Confirm that the configuration is specifically for Hysteria2, not a similarly named but incompatible protocol.
-
Select the type
Go to Home → “+” in the top-right corner → Type, then select Hysteria2. If you imported an existing configuration from shared information, open the entry and check its Type instead of relying on its display name.
-
Enter the settings
Enter the address, port, and authentication details from the original configuration. Check sni, certificate verification, and obfs under the relevant TLS and obfuscation options. For your first test, keep the original bandwidth values and don’t change multiple settings at once.
-
Save and select the entry
After saving, return to Home and select the entry you just added. If Config uses a policy group, check that the active policy selects this entry so you don’t end up testing a different connection.
-
Authorize and test
Turn on the connection switch on Home and approve the VPN configuration when prompted by the system. First, visit a known-working HTTPS page, then check the policy used by the traffic and the connection logs.
Settings → On Demand controls when a connection starts automatically; it does not fix Hysteria2 settings. During troubleshooting, note whether it’s enabled so an automatic reconnect isn’t mistaken for the connection turning itself back on. A connected status on Home means the local VPN session is established. It does not confirm server authentication, access to a destination website, or that every routing rule is working.
Use Global Routing to tell protocol issues from routing issues
If the connection is on but a website won’t load, first determine whether the connection itself failed or the request wasn’t routed through it. Config, Proxy, and Direct under Global Routing are routing modes, not Hysteria2 settings. Scene follows its configured behavior, so check which option is active before troubleshooting. Otherwise, a scene change can be mistaken for a protocol issue.
Config
RecommendedFor everyday use, choose a checked Config and let the rules select DIRECT or a proxy policy. Check the matching DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL rules to confirm the policy ultimately points to the intended Hysteria2 connection.
Best for: everyday use with clear routing requirements and verified rules and policy groups
Proxy
Temporarily route traffic handled by the client through the selected proxy path to reduce variables introduced by Config rules. This remains subject to the scope of system traffic interception and protocol support; it does not mean all device traffic will necessarily use the same path.
Best for: briefly checking whether the connection works and isolating rule-matching issues
Direct
Use a direct route as a baseline for comparison. This mode cannot confirm that Hysteria2 is working because the test request does not pass through that proxy connection.
Best for: checking direct access over the local network to the destination website
Check rules after confirming Proxy works
If the same destination works in Proxy but fails in Config, leave the connection settings unchanged and check the matching rules, policy group, and DNS results first. Don’t change sni, obfs, and the port at the same time.
Troubleshoot by failure stage, not by a single latency result
Latency test results depend on the test method and destination; they don’t represent every type of traffic. A connection with a low test result may still be affected by UDP rate limits during large transfers. If a test times out, assess it alongside actual web requests and connection logs. The table below describes observable symptoms; it does not promise measured performance for any particular route.
| Symptom | Check first | Next step |
|---|---|---|
| Repeated handshake timeouts | DNS resolution, UDP port, restrictions on the current network, and whether obfs settings match. | Keep the configuration unchanged and repeat the same request on another network you’re allowed to use to see whether the issue depends on the access network. |
| Certificate-related error | sni, certificate validity dates, device time, and the trust chain. | Ask your configuration provider to confirm the domain covered by the certificate, and leave certificate verification enabled. |
| Authentication failure | Whether the password is complete and the credentials are still valid. | Copy the original credentials again; don’t substitute the obfs password. |
| Small pages load, but large transfers stall | UDP rate limits, path MTU, packet loss, server load, and bandwidth settings. | Restore the original bandwidth settings, pause other transfers, and test the same destination again. |
| Only some websites fail | Rule matching, policy group selection, DNS results, and the destination’s status. | Temporarily compare with Proxy to determine whether the issue is routing or connectivity. |
A QUIC path must support UDP payloads of at least 1,200 bytes. Some tunnel overlays or unusual network paths can cause packet-size issues. However, a page failing to load is not enough to diagnose an MTU problem. Without clear evidence about the path, don’t change system network settings at random or treat Hysteria2 as if it had a WireGuard MTU field.
Keep test records that can be checked later
- Record the network type, selected entry, Global Routing mode, and test destination so results from different conditions don’t get mixed together.
- On the same network, make the same page request three times. Note whether the handshake succeeds, the page finishes loading, and the connection drops. This is a way to keep records, not a performance metric.
- Change only one setting per test round. If changing the bandwidth setting makes things worse, restore the original value and test again. Avoid piling on changes that make the cause hard to identify.
- When comparing Wi-Fi and cellular networks, keep the configuration and destination the same. Different results mean the access path has an effect, but further checks are needed before concluding that a particular device is at fault.
- Before sharing troubleshooting records, remove the password, obfs-password, full share information, and subscription credentials. Include only the necessary error type and sanitized details about how the settings relate.
Hysteria2 is suitable when the server explicitly supports it, the UDP path is available, and the authentication and TLS settings are complete. Whether it works better on an unstable network depends on repeatable access results. If the current path restricts UDP, increasing the bandwidth setting is not an effective optimization. Address network reachability first, and use a configuration you already have that’s compatible with the network.