This guide is for users who already have their own provider configuration or subscription and need to check Hysteria2 settings in Shadowrocket. It explains the roles of QUIC and UDP, then walks through the server, port, authentication, TLS, and SNI fields. Finally, it shows how to isolate transport, authentication, and routing issues using the same network and request. No nodes or subscriptions are provided, sold, or recommended.
How Hysteria2, QUIC, and UDP work together
In Shadowrocket, Hysteria2 is a proxy protocol type—not a Global Routing mode or an acceleration switch that applies to every connection. A request uses this connection only when the corresponding entry is selected and the request is routed to that entry or a policy that includes it.
Hysteria2 uses QUIC for transport, and QUIC runs over UDP. UDP does not retransmit data or deliver it in order; QUIC adds encryption, stream management, and reliable transport. So “UDP-based” does not mean web data can be lost at will, nor does it make an application's original TCP requests unreliable.
It helps to distinguish the inner connection from the outer one. An app may use TCP to access a website. When Shadowrocket sends that request through Hysteria2, the connection between the device and proxy server uses QUIC over UDP. The destination website does not need to support QUIC. The proxy server's connection to the destination is separate from the transport between the device and the proxy server.
- UDP: Carries datagrams. The network must allow communication between the device and the server on the configured UDP port.
- QUIC: Handles connections, encryption, and streams. Loss on one stream is less likely to block other streams than loss on a traditional single TCP connection, but reliable delivery on an individual stream is still affected by packet loss.
- Hysteria2: Defines authentication, proxy requests, and data forwarding on top of this transport. Client and server settings must match.
Performance and limitations on lossy networks
Hysteria2 includes congestion-control approaches designed for high-latency, lossy links. Its Brutal mechanism is tied to configured bandwidth values. Stable throughput still depends on link capacity, the cause of packet loss, server load, and the congestion-control mode in use. The protocol name alone cannot predict a fixed speed, and more packet loss does not necessarily mean greater gains.
It is especially important to distinguish random loss from congestion loss. If fluctuating wireless conditions cause occasional random loss, a suitable transport mechanism may improve link utilization. If the uplink is already congested, sending more data can increase queueing, latency, and packet loss. Setting bandwidth far above the available upload capacity does not create more capacity.
First check UDP reachability, then adjust bandwidth
If the same configuration works on cellular but consistently times out during the handshake on a particular Wi-Fi network, first check the path from that Wi-Fi network to the server's UDP port. Increasing bandwidth or disabling certificate verification will not fix an unreachable transport.
- Worth evaluating: UDP is reachable, the server settings are clear, and the current link has high latency or random packet loss.
- Use caution: The network heavily restricts UDP, the uplink is persistently saturated, or data usage and battery consumption need to be kept in check.
- Not directly addressed: Incorrect authentication, expired certificates, incorrect rules, or problems with the destination website.
Checking Hysteria2 settings in Shadowrocket
An existing subscription usually includes the server settings, so start by checking the imported entry. Do not mix fields from different entries. To add one manually, tap the add button on Home, select Hysteria2 under Type, and enter the values from your configuration. Field order and available options may change with the app interface; do not substitute other options for advanced settings that are not shown.
| Field or setting | What to enter | Common mistake |
|---|---|---|
| Type | Select Hysteria2 to match the server protocol. | Treating Hysteria and Hysteria2 as interchangeable types. |
| Server address | Enter the hostname or IP address from your configuration. | Pasting the entire subscription URL into the address field, including its path or query parameters. |
| Port | Enter the UDP port the server actually listens on, such as 443 when specified in the configuration. | Assuming every server uses 443, or checking only whether TCP port 443 is reachable. |
| Authentication | Copy the authentication value from your configuration exactly. | Including extra spaces when copying, or using a subscription token as the connection password. |
| TLS / SNI | Keep certificate verification enabled. Set SNI to the server name specified in your configuration. | Using the connection IP address as the certificate name when the two differ. |
| obfs | Configure this only if the server enables it and provides the corresponding settings. | Mixing up the obfuscation password and authentication value, or enabling obfuscation only on the client. |
| Bandwidth settings | If available, use the actual upload and download capacity and the values in the original configuration; check the units. | Confusing Mbps with MB/s, or using a theoretical peak instead of sustainable capacity. |
SNI supplies the server name during the TLS handshake. Certificate verification also checks whether the server's identity matches the expected name. The server address determines where the connection goes; SNI and the certificate name determine which identity is verified. They can differ, but there must be a clear basis in the configuration. If a certificate error occurs, check the name, device time, and server certificate rather than routinely skipping verification.
Hysteria2 is not directly compatible with the protocol and settings used by earlier Hysteria versions. If an entry is misidentified after a subscription update, check whether the original entry explicitly specifies Hysteria2 and whether the app can read that subscription format. Renaming an entry does not change its protocol.
Importing and updating a subscription, then testing the connection
A subscription URL is used to retrieve configuration; it is not a proxy server address. It may contain credentials that allow access to the configuration, so treat it as sensitive information. This example is only to illustrate the format and cannot be used to connect: https://example.com/sub?token=xxxx. Do not include a real subscription link in public screenshots or troubleshooting notes.
- Import an existing subscription: On Home, tap the add button, select Subscribe under Type, enter your own subscription URL in URL, and save. Return to Home and check that the group appears and contains a recognizable Hysteria2 entry.
- Check the update: To refresh a subscription, select Update for that subscription. When it finishes, check the entry type, server, and port. If retrieval fails, first determine whether the subscription URL or the proxy server is unreachable; do not treat these as the same error.
- Select an entry to test: On Home, select the Hysteria2 entry you want to verify and note its name and port. If a policy group selects the outbound route, also confirm that the group has selected this entry.
- Control routing variables: Temporarily select Proxy under Global Routing to test the chosen route, then restore your usual routing mode. Direct does not test the proxy connection. Config depends on the rules in the active configuration.
- Connect and make a request: Turn on the connection switch. The first time, follow the system prompt to authorize the VPN configuration. Then open a page known to work and check for handshake, authentication, certificate, or DNS resolution errors.
- Restore your everyday setup: Return to Global Routing → Config and check which rule and policy match the same request. Make sure it is not working under Proxy but being routed through a different exit when your rules are restored.
Distinguishing handshake timeouts, certificate errors, and routing issues
Troubleshooting by connection stage is more effective than repeatedly changing every field. First note the current network, selected entry, Global Routing mode, and error message; then change one setting at a time. A latency test returning a result shows only that the parts covered by that test responded. It does not replace a real web request or prove that every UDP forwarding scenario works.
Does the same entry time out on Wi-Fi but work on cellular?
Keep the server, port, and authentication value unchanged, and retest on a different network. If the difference is consistent, first check the Wi-Fi network's UDP restrictions, routing, and firewall. Access to TCP port 443 does not prove that UDP port 443 is reachable. Hysteria2 will not switch to TCP automatically if UDP is blocked.
The certificate name does not match. What should I change?
On Home, edit the entry and compare its server address and SNI with your configuration. Check that the device date and time are correct. If the address is an IP but the certificate is issued to a domain, use the name specified in the configuration for verification. If the error persists, the server certificate needs to be checked; do not disable verification.
Why does it work under Proxy but not Config?
In Config, confirm which configuration is active, then check the rule order and target policy. Rules generally match from top to bottom; DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL may send the same request to different policies. Check the actual match first rather than assuming the Hysteria2 handshake failed.
Why does latency rise noticeably after sustained transfer, even though the connection starts well?
First stop other tasks using the uplink. Check the bandwidth settings and units in your configuration, then retest with the same request. If the interface offers adjustable settings, lower them gradually and watch queueing latency. Do not change the port, SNI, and authentication value all at once, or you will not know which change made a difference.
If only certain websites fail, check DNS resolution, rule matching, and restrictions on the destination service separately. An enabled connection switch only indicates that the system VPN is in the corresponding state; it does not mean every domain uses the same route. To connect automatically, Settings → On Demand controls when the connection starts; it does not fix incorrect Hysteria2 authentication or a wrong port.
Evaluate suitability under consistent network conditions
Base your evaluation on your everyday network, not a single peak-speed result. Keep the device, server, destination, and Global Routing mode consistent; repeat tests at similar times and record Wi-Fi and cellular results separately. Without data collected under comparable conditions, do not claim a specific percentage improvement.
- Track connection success: For example, try five times, disconnecting before each attempt, and record the number of successful connections and where failures occur. This is a test method, not protocol performance data.
- Track responsiveness: Observe the first response from a page and how it responds during sustained transfers. Higher average throughput does not necessarily mean a faster initial page load.
- Track the effect of changing networks: Switch from Wi-Fi to cellular and make the request again. Whether an active session continues depends on the network and implementation; the name QUIC alone is no guarantee.
- Track resource use: Keep an eye on data consumption and battery usage. Retransmissions and other overhead can make measured usage exceed the size of the app's content, so assess it under real-world use.
Keep the settings that reproduce the issue consistently, then restore your everyday Config routing. If the problem occurs on only one network, investigate that path first. Choose Hysteria2 based on UDP reachability, correct settings, and repeatable test results—not as a universal fix for every connection issue.