VMess and VLESS cannot be converted into each other by changing only the Type. For users who already have an authorized, working configuration, this guide explains the roles of the protocol, UUID, Transport, and TLS, and how to check each field in Shadowrocket’s Add Server form. Start with the parameters in your existing configuration, then verify the connection in the logs. A protocol name alone does not guarantee speed or security.
Key differences between VMess and VLESS
Shadowrocket supports connection configurations for multiple protocols. Both VMess and VLESS can use a UUID as a user identifier, but their authentication methods, data handling, and supported combinations differ. If the server is configured for VMess, select VMess in the client; if it uses VLESS, select the matching type. The same address, port, and UUID do not make the protocols interchangeable.
| What to check | VMess | VLESS |
|---|---|---|
| Identity | Uses authentication parameters such as a UUID; authentication also depends on time validity | Uses a UUID to identify and authenticate users; it does not use VMess authentication |
| Built-in data encryption | Supports encryption within the protocol; details depend on the selected encryption setting | Common configurations use encryption set to none; no equivalent payload encryption is built in |
| Transport security | Can be combined with TLS; protocol-level encryption is not the same as TLS | Typically relies on TLS or another security layer specified by the configuration |
| Transport | Must match the server’s Transport, such as TCP or WebSocket | Must also match the server’s Transport; the protocol name alone is not enough |
| Migration | Use the complete VMess parameters provided by the server | Use the complete VLESS parameters provided by the server; don’t just edit an existing entry |
“VLESS has no equivalent built-in payload encryption” does not mean the entire connection is necessarily unencrypted. When VLESS is correctly used over TLS, the outer TLS layer protects data between the client and the corresponding TLS endpoint. Conversely, seeing TLS in a configuration is not enough: check certificate validation, name matching, and the actual connection result.
Separate the three layers: protocol, Transport, and TLS
A connection can use VLESS, WebSocket, and TLS together: VLESS handles protocol-level processing, WebSocket provides the transport encapsulation, and TLS handles outer-layer encryption and certificate validation. These are not mutually exclusive options. VMess can also be combined with WebSocket and TLS; WebSocket is not exclusive to VLESS.
Bottom line: enter the complete set of parameters; don’t infer defaults from the protocol name
If your existing configuration doesn’t specify the Transport, TLS, or port, verify the original parameters first. Don’t assume WebSocket, enable TLS, or switch to port 443. Change only one confirmed incorrect field at a time so you can tell whether the fix worked.
A UUID is not an address or a subscription link. It commonly consists of five groups of hexadecimal characters in the format 8-4-4-4-12. When copying it, avoid leading or trailing spaces, line breaks, and full-width characters. Even a correctly formatted UUID may fail authentication if the server hasn’t authorized it, so checking the format is only the first step.
- Address: The host to connect to first. If you enter an IP address, don’t assume the SNI should be the same IP.
- Port: The listening port to connect to.
443and8443are only possible values; use the parameters you already have. - Transport: How the protocol data is carried. If you select WebSocket, check the Host and Path as well.
- TLS: Covers the secure handshake, server name, and certificate validation. Changing the UUID won’t fix a certificate name mismatch.
Add Server fields users most often get wrong
In Home, tap the add button to open Add Server. Select Type first, then fill in the relevant fields. The options shown next depend on the Type, Transport, and in-app settings; use the table below to check what each parameter means, rather than expecting every protocol to have the same editing form. If an existing subscription imports correctly, keep the imported entry instead of rebuilding it from memory.
| Field or parameter | What to check | Common mistake |
|---|---|---|
| Type | Match the server protocol; distinguish VMess from VLESS | Changing only Type while keeping parameters for the other protocol |
| Address / Port | Enter the address and numeric port separately | Pasting a full URL, including its path, into the address field |
| UUID | Copy the complete user identifier without any explanatory text | Copying the display name or missing one group of characters |
| VMess encryption setting | Follow the existing configuration and the options supported by the server | Applying VLESS’s none setting to VMess without checking |
| Transport | Match the server’s TCP, WebSocket, or other Transport settings | Assuming port 443 means WebSocket is in use |
| WebSocket Host / Path | Use the specified hostname for Host; preserve the leading slash in Path and any required query parameters | Using SNI as the Path, or omitting the leading slash from the path |
| TLS / SNI | Check whether TLS is enabled and which server name should be sent | Using the connection IP as the domain name on the certificate |
| Allow Insecure | Keep certificate validation enabled; fix certificate, name, or device-time issues first | Treating skipped validation as a long-term fix |
For example, an existing configuration might require connecting to an IP while setting both SNI and the WebSocket Host to edge.example.com, with Path set to /tunnel. These parameters are related in this example, but each has a different role: Address identifies the connection target, SNI indicates the name during the TLS handshake, and Host is used in the WebSocket HTTP handshake. The example domain and path illustrate how the fields relate; they are not a working connection configuration.
From import to verification: keep the original configuration, then check routing
Correct protocol parameters don’t guarantee that a request is using the connection. The selection in Home, the Global Routing mode, and the rules in Config together determine where traffic goes. When troubleshooting, separate “is the connection itself working?” from “is the request matching the expected rule?”
- Import an existing configuration or subscription you’re authorized to use, then check the number of entries and their Type in Home. If entering one manually, first check the fields described in the previous section.
- Select the entry you want to test and connect. The first time, follow the system prompt to allow adding a VPN configuration.
- Check the current Global Routing mode. Don’t leave it on Direct and then use a webpage result to judge whether the protocol works.
- Make a request to a target you’re authorized to access and can test repeatedly. Check the in-app connection logs for the target, policy, and any error details.
- If you need to update an existing subscription, check the currently selected entry again afterward. Subscription updates may overwrite manual changes, so keep a private backup of important edits.
Config
RecommendedTraffic follows the currently enabled configuration rules. Once protocol testing is complete, restore the Config you checked and see which policy the request actually matches. A request can verify this connection only if its rule points to the current proxy.
Best for: everyday use with existing rules and verifying that they work
Proxy
Routes requests handled by Shadowrocket through the proxy. This can temporarily reduce interference from rule-based routing, but it won’t fix protocol settings or an incorrect UUID, Port, or TLS configuration.
Best for: briefly distinguishing connection-parameter issues from rule-matching issues
Direct
Uses a direct connection. It is not suitable for checking whether the selected VMess or VLESS connection can forward traffic. If a page opens directly, that only shows the target is reachable under the current direct-connection conditions.
Best for: comparing direct connectivity with reachability of the target itself
Global Routing also includes Scene. Check the settings applied by the current scene rather than judging traffic flow by its name. Settings → On Demand triggers connections under specified conditions; it doesn’t change VMess or VLESS authentication parameters. If the connection starts automatically, check this setting. If authentication fails, check the parameters in the relevant entry.
Troubleshooting timeouts, authentication failures, and certificate errors
An error can help narrow down the cause, but it can’t prove which field is wrong on its own. Record the original values, then check in this order: address reachability → secure handshake → protocol authentication → request routing. This avoids losing track of what fixed the issue after changing several things at once. The answers below suggest troubleshooting steps; they are not definitive explanations for every error message.
Why does the connection still time out when the UUID is correct?
Open the entry’s edit screen in Home and check Address and Port first, then see whether the current network can reach the target. A timeout can occur before authentication or because a later handshake doesn’t complete; don’t keep generating or replacing the UUID. If the configuration worked before, check the existing service status and the result of the latest subscription update.
The certificate name doesn’t match. Should I enable Allow Insecure?
Check the TLS server name and SNI, verify the device’s date and time, and confirm that the server certificate is still valid. If Address is an IP but the certificate was issued for a domain, enter the correct name from the original configuration. Don’t bypass certificate validation instead of fixing a name or certificate issue.
My VMess settings haven’t changed, but I’m suddenly seeing an authentication error. What should I do?
First check that the device’s date and time are correct. Then verify that the UUID is still authorized and that the server parameters haven’t changed. VMess authentication depends on time validity, so a significant clock difference can cause failures. Don’t repeatedly try arbitrary AlterId values from an old configuration; use the currently valid parameters.
VLESS is connected, but webpages still won’t load. What should I check next?
Check the in-app connection logs to confirm that the webpage request used the expected policy. If it reached the target connection, check the Transport, WebSocket Host and Path, TLS, and any additional parameters required by the configuration. A VPN-connected status doesn’t mean remote authentication, DNS resolution, or every request to a target has succeeded.
A latency test returning a value doesn’t mean every webpage is reachable. Different test methods may cover different stages, so verify with an actual request. Before sharing troubleshooting details, remove UUIDs, subscription tokens, passwords, and other access credentials. The Type, Transport, error category, and redacted relationships between fields are usually more useful for identifying the issue.
Choosing and migrating: use your existing configuration and test results
If your current VMess configuration works, there’s no need to migrate just because VLESS has a different name. VLESS lacks equivalent built-in payload encryption, but that doesn’t mean it is “always faster.” The outer security protocol, transport method, network quality, server load, and destination all affect results. For a comparison, use the same test targets under similar network conditions and record connectivity, the stage where failures occur, and results across repeated tests—not just a single latency reading.
- Only one valid configuration: Enter its parameters as provided; don’t change VMess to VLESS on your own.
- Two authorized configurations: Create a separate entry for each and test them individually. Don’t overwrite the only working entry.
- Switching protocols: Get the complete parameters again and confirm the UUID, port, Transport, TLS, and additional options. Don’t assume any field can be reused.
- Keeping a configuration long term: Securely back up the working configuration and any necessary notes. Don’t publicly share screenshots or files containing credentials.
Shadowrocket is a closed-source, paid app for Apple platforms, primarily used on iPhone and iPad, and available exclusively through the App Store. The app is a one-time purchase; buying the app is separate from using a connection service. This guide assumes you already have your own provider and subscription; it does not provide, sell, or recommend connection services. Check the App Store listing for system requirements and purchase availability.