This guide is for users who already have server parameters or a subscription and want to check their VMess or VLESS settings in Shadowrocket. First, distinguish the protocol, credentials, transport, and TLS; then check the fields in the order they appear under Home → Add Server. You’ll learn what UUID, alterId, encryption options, Host, and SNI each do, and how to narrow down connection problems by identifying where they occur.
1. VMess vs. VLESS: Protocol Encryption Is Not TLS
Shadowrocket stores connection parameters in server entries. VMess and VLESS are protocol types—not Global Routing modes or names for the TLS toggle. Which one to choose depends first on the existing server configuration. Changing the client’s Type alone cannot convert the same service from VMess to VLESS.
VMess provides authentication and optional data encryption at the protocol layer. Common encryption options include auto, aes-128-gcm, and chacha20-poly1305. VLESS does not provide a general-purpose data encryption layer; in a typical configuration, encryption=none describes this layer and does not mean that outer TLS should also be disabled. For either protocol, configure transport and the security layer as required by the server.
| What to check | VMess | VLESS |
|---|---|---|
| Credentials | Usually a UUID; it must match the server | Usually a UUID; it must match the server |
| Protocol-layer encryption | Encryption method can be configured; use the value specified in your service parameters | Typically set to none for encryption; this layer does not provide data encryption |
| alterId | Legacy compatibility parameter; usually 0 with modern VMess AEAD configurations | Not used for this protocol |
| TLS and transport | Check separately; don't infer these from the protocol name | Check separately; don't infer these from the protocol name |
VLESS flow is not a replacement field for VMess encryption. If your existing parameters specify flow, confirm that the selected Type, transport, and security settings support that combination, then enter the value as provided. Don't add it to a standard VLESS configuration on your own. The same protocol name does not mean every extended configuration is interchangeable.
2. Check Address, Port, and UUID in Add Server
On Home, tap the add control in the upper-right corner to open Add Server. Select VMess or VLESS under Type, then enter the remaining fields. The fields shown vary by type, and labels may differ with the app’s language and version. Check what each field means; don’t change the protocol type just to find an option with a similar name.
- Address: Enter the domain name or IP address provided for your existing service. A standard Address field does not include
https://, a path, or subscription query parameters. Don’t paste a full subscription URL here. - Port: Enter the port the server actually listens on.
443is only an example; it does not mean every TLS service uses the same port. - UUID: Copy the existing credential exactly, removing any leading or trailing spaces and line breaks. A UUID that looks correctly formatted may still not be authorized by the server.
- Protocol-specific fields: For VMess, check the encryption option and alterId. For VLESS, check parameters such as encryption and flow if they were provided. If a field is missing, confirm the selected Type and its supported options rather than putting the value in Notes.
- Transport and TLS: Next, check Transport, TLS, and their related fields. Verify everything before saving. Notes are for identifying an entry and do not affect server authentication.
For example, 123e4567-e89b-42d3-a456-426614174000 illustrates the text format of a UUID; it is not a usable credential. A UUID is also different from a token in a subscription URL: the former is used for server authentication, while the latter may grant access to an entire subscription. Never share real values of either kind when troubleshooting.
3. Setting VMess alterId and Encryption Options
alterId is a legacy compatibility parameter in VMess configurations. Some shared configurations use aid for the same field. Modern VMess AEAD configurations typically use 0. This 0 does not disable authentication or TLS. If your existing parameters contain a nonzero value, confirm compatibility with your service provider before changing it; don’t adjust it at random to try to improve speed.
- Existing parameter is auto: Use the value provided and let the implementation choose an appropriate encryption method. Don’t change it just because you’re using a different device model.
- An algorithm is specified in the existing parameters: Check that it’s supported, then enter the specified value. The encryption option controls data handling at the VMess protocol layer; it does not verify certificate domain names.
- You see none or zero: Don’t treat either as a universal substitute for auto. Each has a specific meaning and conditions for use, so confirm it against the server configuration.
- No separate alterId field appears after import: Keep the imported settings for now and check the original parameters and current support. Don’t append the number to UUID, Address, or Port.
VMess authentication also depends on time. If all parameters match but authentication keeps failing, check that the date and time on your Apple device are accurate and use the system’s automatic time setting if available. Correcting the time only rules out this one possible cause; it won’t fix an incorrect UUID, expired authorization, or an unreachable server port.
4. What Transport, TLS, Host, and SNI Do
Transport determines how protocol data is carried, such as over TCP or WebSocket. TLS secures the connection and validates the certificate. Address is the destination used to establish the network connection; SNI is the server name sent during the TLS handshake; and the WebSocket Host is an HTTP request header. These values may match in some configurations and differ in others, so don’t use them interchangeably.
| Field or parameter | What to enter | Common symptoms of an incorrect value |
|---|---|---|
| Transport | Must match the transport configured on the server, such as WebSocket | Port is reachable, but the protocol connection cannot be established |
| Path | For example, /edge; preserve the leading slash, capitalization, and any required query parameters | WebSocket handshake fails; may return HTTP 404 |
| Host | The HTTP Host required by the existing service, such as edge.example.com | Request reaches the wrong site; may return 403 or 404 |
| TLS / SNI | Enable TLS as required by the service and enter the specified server name | Certificate name mismatch or TLS handshake failure |
The domains and paths in this table are text examples, not connection endpoints. HTTP status codes are clues for troubleshooting, but a 403 or 404 alone cannot identify the incorrect field; reverse proxy configuration can produce the same result. Compare the required Host and Path with the values currently entered in the client.
Enable TLS as specified in the existing parameters and validate the certificate
RecommendedIf the service explicitly requires TLS, leave it enabled, enter the correct SNI, and keep certificate validation on. If there’s a certificate error, check the device time, domain name, and server certificate first rather than skipping validation.
For: VMess or VLESS connections whose existing parameters specify TLS
Leave TLS disabled if specified in the existing parameters
Keep TLS disabled only when the server explicitly uses a non-TLS transport. Enabling TLS on the client alone causes a handshake mismatch. VLESS does not provide data encryption itself, so a regular non-TLS connection is not an equivalent encrypted connection.
For: Controlled tests or other established security-wrapped setups explicitly specified by the service provider
Bottom line: For TLS errors, check the server name before changing the UUID
If the error clearly occurs during certificate validation, first compare SNI, the domain names covered by the certificate, and the device time. Keep the UUID and transport parameters unchanged, make the correction, and test again. This makes it easier to identify which setting was responsible.
5. After Saving: Separate Connection Problems from Routing Problems
Saving a server only records its parameters; it doesn’t make that entry active. On Home, select the server you want to use, set it as the active entry, and turn on the connection. The first time you connect, follow the system prompt to allow adding a VPN configuration. Then run Connectivity Test and note which entry was tested, the Global Routing mode, and any error message.
- Check basic reachability first: If the test times out, check Address, Port, and your current network. If the port is unreachable, repeatedly changing the UUID or WebSocket Path usually won’t help.
- Then check security and authentication: For certificate errors, check TLS and SNI. For authentication failures, check the UUID, VMess alterId, and device time. Refer to the error message actually shown in the app.
- Then check the application-layer transport: If TCP connects but WebSocket fails, compare Transport, Host, and Path. A latency reading alone does not prove the entire proxy connection works.
- Finally, check routing: Direct under Global Routing does not use a proxy to test the target traffic; Config handles connections according to its rules. To rule out rule-related issues, you can temporarily use Proxy to test the same destination, then restore the previous mode.
In Config mode, rules such as DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL determine which policy handles a connection; they cannot fix protocol authentication failures. For example, DOMAIN-SUFFIX,example.com,PROXY sends matching domain suffixes to the PROXY policy. If that policy isn’t using the entry you just edited, the current request won’t use your changes.
If you need to control when tests run, also check the current Settings → On Demand configuration so automatic connection behavior doesn’t interrupt your observations. During troubleshooting, change one field at a time and reconnect after switching servers or changing key parameters. Don’t change the protocol, TLS, rules, and DNS all at once; even if the connection starts working again, you won’t know why.
6. Common Questions About UUIDs, Subscription Imports, and Switching Protocols
Can I switch from VMess to VLESS using the same UUID?
Not based on the UUID alone. First confirm that the server provides a VLESS endpoint. Then create a new entry under Home → Add Server, select the corresponding type, and enter that endpoint’s address, port, UUID, transport, and security parameters. Keep the original entry for comparison rather than overwriting your only working configuration.
Why enable TLS if VLESS encryption is set to none?
They operate at different layers. encryption=none means VLESS does not provide data encryption at its own layer. If the service requires TLS, enable it in the entry and enter the correct server name. Don’t disable TLS automatically just because the value is none.
If the subscription already contains entries, do I need to add them one by one?
Usually not. For an existing subscription, open the add menu on Home, choose Subscribe, enter the full subscription URL in URL, then save and update. Open an imported server entry to check its fields. The subscription URL retrieves entries; it is not the VMess or VLESS Address.
Why did my Host change revert after updating the subscription?
Subscription entries are maintained by the subscription content, and an update may overwrite local changes. Save any parameters you need for comparison, then create a separate manual test entry for troubleshooting. For a lasting correction, check the original subscription content. A temporary local change does not mean the subscription source has been updated.
If both protocols can be imported, which one should I keep?
Test authentication, TLS, and transport parameters for each, using the same network, destination, and routing mode. Keep the entry that matches the existing server configuration and passes the test. The protocol name alone cannot guarantee latency or throughput, nor replace a connectivity test.
This guide assumes you already have your own service and subscription; it explains fields and how to use them. When sharing troubleshooting details, you can provide the protocol type, transport, whether TLS is enabled, the stage at which the error occurs, and a redacted field structure. Keep UUIDs, full subscription URLs, and other credentials private.