VMess and VLESS are different Types, not interchangeable options. Both use UUIDs to identify users, but their authentication mechanisms and in-protocol encryption differ. TLS, transport, Host, and Path must also match the server configuration. This guide is for users with their own provider configuration or subscription who are ready to import it into Shadowrocket or enter it manually. Follow these steps: choose the right Type, verify authentication, check transport, then troubleshoot layer by layer.
Bottom line: Type must match the server
VMess is a proxy protocol with authentication and optional payload encryption. VLESS has a simpler protocol structure and does not encrypt payloads itself, so transport is usually protected by an outer security layer. Both use the same UUID format, but that does not mean a server endpoint supports both protocols. Changing an existing VMess entry’s Type to VLESS while leaving the other fields unchanged does not convert the protocol.
Before adding a server, make sure you have all the required details. In addition to Address, Port, and UUID, confirm the transport and security settings. Port 443 is just a port number: it does not prove that TLS is enabled or indicate whether the protocol is VMess or VLESS.
| Field to check | VMess | VLESS |
|---|---|---|
| User ID | Uses a UUID as part of VMess authentication | Uses a UUID with VLESS authentication |
| alterId | Related to legacy authentication; typically 0 with modern AEAD configurations | No equivalent alterId parameter |
| In-protocol encryption | Has Security options that must match the server | Does not encrypt payloads at the protocol level; encryption in links is usually set to none |
| Outer security layer | Check TLS and other settings separately | Check TLS and other settings separately; none does not configure a security layer |
| Transport | TCP, WebSocket, and other options must match the server | TCP, WebSocket, and other options must match the server |
Bottom line: confirm the full settings before choosing a Type
If you only have an address, port, and UUID, check the transport and security settings with your provider first. Don’t try to fill in missing details by switching the Type or cycling through encryption options.
Adding a server: preserve all fields in the existing configuration
In Home, open Add Server from the add menu, select the Type specified in your details, and fill in each field. Manual entry works when you have complete settings and need to check each field. If you already have a complete share link or subscription, importing it can help prevent missing parameters such as Host and Path. After importing, open the entry and verify its fields rather than relying on its display name.
Import an existing complete configuration
RecommendedImport a share link or subscription you already have, then check Type, Address, Port, TLS, and transport settings. Importing helps reduce transcription errors; it doesn’t mean every configuration source can be trusted.
Best for: complete links or subscriptions with multiple parameters
Enter details manually in Add Server
Enter each value from the parameter list. Choose the Type first, then check the options that appear for that protocol. Before saving, make sure you haven’t copied parameters from a different protocol.
Best for: a complete parameter list that you need to verify field by field or troubleshoot
- In Home, select the entry you want to use and open its edit screen to check the Type. Don’t rely on “VMess” or “VLESS” in the name to identify the actual protocol.
- Enter Address and Port in separate fields. Address is usually a domain name or IP address. Don’t paste a complete share link with a path into the Address field.
- Copy the full UUID. Check for extra spaces, line breaks, or quotation marks, then fill in the options for the selected protocol.
- Check the TLS and transport settings. After saving, reopen the entry to make sure no fields are missing.
A share link describes a single connection entry, while a subscription address retrieves and updates a group of entries. For example, https://example.com/sub?token=xxxx is an example of a subscription URL format that won’t work; it is not an example of what to enter in Address. Subscription updates may recreate entries. Before troubleshooting, note any manual changes so you don’t mistake an overwritten setting for one that failed to save.
Authentication fields: check UUID and alterId separately
A UUID identifies a user; it is not a server domain or a token from a subscription address. A common text format is 36 characters with hyphens, such as 123e4567-e89b-42d3-a456-426614174000. This is a format example, not a working credential. A UUID that looks valid is not necessarily authorized by the server.
VMess alterId is not a latency or speed setting. Legacy VMess authentication used non-zero alterId values, while modern VMess AEAD configurations typically use 0. If older documentation specifies another value, check which authentication method the server currently uses instead of increasing the value yourself. VLESS has no equivalent alterId, and it should not be copied into another field.
- Incorrect UUID: Even if the TCP port is reachable, protocol authentication may still fail. The request may be interrupted, closed, or time out.
- VMess authentication mismatch: Requests can fail even when the address and port are correct. Check both alterId and the server’s AEAD requirements.
- Incorrect device time: VMess authentication involves time checks. On your iPhone or iPad, go to Settings → General → Date & Time and confirm the time and time zone are correct.
- Duplicate entry names: A name is only a label; it is not used for authentication. Compare the actual fields. Renaming an entry does not change its UUID.
Encryption and transport: none does not mean TLS is off
In-protocol encryption and outer TLS operate at different layers. VMess Security options may include values such as auto, aes-128-gcm, and chacha20-poly1305. Use the values required by the server and available in the app. Don’t enter a VMess encryption value in the corresponding VLESS field, or choose none at random to try to improve speed.
In VLESS share parameters, encryption=none means VLESS does not encrypt payloads itself; it does not mean the outer connection needs no protection. If the original configuration uses TLS, keep TLS enabled after importing. If it uses another security mechanism, match all its specific parameters. Enabling standard TLS alone is not a substitute.
How to check: record security and transport settings separately
TLS security layer
- Confirm whether the server requires TLS; don’t infer it from the port.
- Check SNI, the server name used in the TLS handshake.
- Make sure the certificate covers the domain used for SNI.
- Keep certificate verification enabled; fix the domain or certificate to address errors.
WebSocket transport layer
- Confirm the transport is WebSocket, not plain TCP.
- Check Host; don’t assume it matches Address.
- Compare Path character by character, including the leading slash.
- Match capitalization and preserve any required path parameters.
Address, SNI, and WebSocket Host may be the same or different. Use the values from the original configuration for each field; don’t substitute them automatically.
For example, suppose the settings list Address as edge.example.com, Port as 443, SNI as tls.example.com, WebSocket Host as web.example.com, and Path as /connect. Check these as five separate fields. These are placeholder values for illustration, not a usable connection configuration.
Connection failures: troubleshoot by layer, not by latency alone
A latency test returning a value only shows that the steps covered by that test received a response. It does not, by itself, prove that the UUID, TLS, transport, and access to the destination website are all working. Test methods cover different layers. When troubleshooting, note the test method, error text, and where the failure occurs. The table below maps symptoms to checks; an error message alone does not establish the cause.
| Symptom | Check first | Next step |
|---|---|---|
| Server domain lookup fails | Address spelling and DNS resolution on the current network | Check the original address and make sure it doesn’t include a protocol prefix or path |
| Connection times out or is refused | Address, Port, and network reachability | Confirm the port matches the server’s current listening port |
| TLS certificate or handshake error | TLS setting, SNI, system time, and certificate | Correct mismatched settings; don’t routinely disable certificate verification as a workaround |
| WebSocket handshake returns 400 or 404 | Host, Path, transport, and server routing | Compare the path character by character; the status code alone doesn’t prove the UUID is wrong |
| Request is closed after the handshake | Type, UUID, and VMess authentication settings | Restore the original settings, then check whether the server accepts the user |
| Test responds, but websites won’t load | Global Routing, selected entry, and DNS | Confirm the request is actually using that entry, then check rules and DNS separately |
- Keep a record of the original settings. Store anything containing a UUID or subscription token somewhere secure and don’t share it publicly.
- In Home, select the entry you want to test and temporarily set Global Routing to Proxy to reduce interference from Config rules. Keep in mind that in-app traffic handling and system limitations may still affect the results.
- Make the same website request and note whether the error occurs during connection, TLS, transport, or the request itself. Change one field at a time.
- After testing, restore the original Global Routing setting. If Proxy works but Config doesn’t, check rule matching and policies in Config rather than repeatedly changing the UUID.
In Config mode, rules determine which policy a request uses. For example, DOMAIN-SUFFIX,example.com,DIRECT sends the matching domain directly. So even when the selected entry in Home works, that request may not use it. Temporarily eliminating rule interference helps distinguish a protocol configuration problem from a request that isn’t using the selected entry.
FAQ: switching protocols, subscription updates, and missing fields
VMess works. Why does switching to VLESS fail right away?
Restore the original Type first. The server must provide a VLESS endpoint and its corresponding port, UUID, transport, and security settings before you can create a separate VLESS entry. Renaming an entry or switching its Type in the client doesn’t change which protocols the server supports.
There’s no alterId field for VLESS. Am I missing a setting?
No. alterId is a VMess-related parameter. Return to Add Server and confirm the Type is VLESS, then enter the UUID, transport, and security settings from the original details. Don’t look for another field to use in place of alterId.
I only have a UUID and port 443. Can I just turn on TLS?
There isn’t enough information to tell. Ask your provider to confirm Address, whether TLS is required, SNI, and the transport. If it uses WebSocket, you’ll also need Host and Path. If details are missing, pause before trying different values so you can preserve useful troubleshooting clues.
What should I do if a subscription update resets my Path?
Open the updated entry in Home and compare it with the original subscription settings and your change notes. The source determines subscription contents, so ask your provider to correct the source configuration. To test a change temporarily, create a separate manual entry rather than assuming the subscription has been fixed.
Choosing between VMess and VLESS depends first on what the existing server supports, then on its transport and security settings. The protocol name alone doesn’t indicate speed. Shadowrocket uses configurations users already have; app purchases and network services are managed separately. This site does not provide, sell, or recommend nodes or subscriptions.