This guide is for users who already have a service provider and configuration and want to add VMess or VLESS in Shadowrocket. First, distinguish the protocol, transport, and TLS layers, then check Address, Port, UUID, Host, and Path in order. You’ll learn which fields must be copied exactly and which settings can’t be inferred from the protocol name. This guide does not provide servers or subscriptions.
VMess vs. VLESS: Similar authentication, different encryption responsibilities
VMess and VLESS are proxy protocols used between a client and server; neither is a server address or a transport method. Both commonly use a UUID to identify the user, but their handshakes differ. You can’t keep an existing VMess profile working by simply changing its Type to VLESS. The server must provide an endpoint for the selected protocol.
VMess supports data encryption at the protocol layer; the specific method depends on the configuration. VLESS does not provide data encryption at this layer and is usually used with a security layer such as TLS. So “VLESS has no protocol-layer encryption” does not mean a VLESS connection is necessarily unencrypted, and it is not a reason to disable TLS in the client.
| Check | VMess | VLESS |
|---|---|---|
| User authentication | Usually uses a UUID, which must match the server record | Usually uses a UUID, which must match the server record |
| Protocol-layer encryption | Supported; specified in the configuration | Does not provide encryption at this layer |
| TLS | Whether it is enabled depends on the server endpoint | Usually paired with a security layer; check the configuration |
| Transport | Must match the server, such as TCP or WebSocket | Must also match the server; the protocol name alone doesn’t tell you which to use |
| Additional parameters | If the configuration includes AlterId, check it exactly | If the configuration includes Flow, confirm the required support |
Decision: Confirm the server endpoint before choosing Type
Check the configuration details and confirm whether they explicitly specify VMess or VLESS. Create a separate profile for the other protocol only if the server provides another endpoint. Don’t try to “upgrade the protocol” by changing Type.
The protocol name alone doesn’t tell you whether a connection will be faster. Network routes, server load, transport settings, and certificate status all affect performance. When troubleshooting, keep the original profile and create a separate test profile; this makes it easier to isolate problems than changing several fields in one profile.
Add Server: Start with Address, Port, and UUID
On Home, tap the add button in the upper-right corner to open Add Server. Select Type, then fill in the fields shown for that protocol. Available options may differ by Type. This guide uses UUID to mean the user identifier provided by your service provider; the form may label it User ID or something similar. Don’t confuse it with a profile name or subscription access token.
- Check Address. Enter the server’s domain name or IP address. If the details list the address and port separately, enter them in their respective fields. Don’t add a web protocol prefix to the address or append the WebSocket Path to it.
- Check Port. Enter the integer port specified by your service provider. For example, if the configuration lists
443, enter443. This port is commonly used for TLS services, but the number alone does not confirm that TLS is enabled for this endpoint. - Check UUID. Copy the complete value and check for leading or trailing spaces, missing characters, and line breaks. A UUID commonly consists of 32 hexadecimal digits grouped by hyphens. Don’t generate your own value to replace the one assigned by the server.
- Check protocol-specific options. Use the existing configuration as the source of truth for VMess encryption options and AlterId, as well as parameters such as Flow in a VLESS configuration. Don’t copy unspecified values from another profile.
- Save and return to Home. Confirm that the new profile appears in the SERVER list and is selected. Seeing it in the list means it was saved; it does not mean the connection succeeded.
If you imported a profile from your own subscription, check the imported result before creating another profile manually. A subscription may include transport and security parameters as well. Copying only the address, port, and UUID can leave out fields required to complete the connection. Before editing a subscription-generated profile, save a separate copy so an update won’t overwrite your changes.
Transport: How TCP, WebSocket, Host, and Path fit together
Transport determines how proxy data is carried; it does not replace UUID authentication. VMess and VLESS can both use different transport methods, depending on the server configuration and current client support. Host and Path have specific request semantics when WebSocket is selected; they are not fields that every connection needs.
| Field | Purpose | Common mistake |
|---|---|---|
| Transport | Choose the transport that matches the server | The server requires WebSocket, but the client is still set to TCP |
| Host | The HTTP Host used in the WebSocket handshake; it may be used for server routing | Using the server IP as Host by default, replacing the configured domain name |
| Path | WebSocket request path, such as /ws | Omitting the leading slash or changing the letter case |
| SNI | Server name used during the TLS handshake | Assuming that entering Host automatically sets SNI as well |
For example, the configuration may specify Address edge.example.com, Port 443, Transport WebSocket, Host gateway.example.com, and Path /ws. These values illustrate how the fields relate; they are not a working server configuration. Address and Host can differ without being incorrect. Don’t change them to match just for consistency.
- Copy Path exactly, including letter case, a trailing slash, and any query string explicitly included in the configuration.
- Don’t enter a full web address in Host. If the form has separate Host and Path fields, fill them in separately.
- If your service provider specifies another transport, check its dedicated fields instead of applying WebSocket’s Host and Path settings.
TLS: Enable it when the endpoint requires it; don’t infer it from the port
TLS provides the connection’s security layer. When it is enabled, check the server name and certificate validation—not just whether the toggle is on. Address can be the IP or domain used to reach the server, while SNI is the name sent in the TLS handshake. If the configuration requires domain validation, enter the specified domain.
The comparison below covers security settings in the same client; it does not rank VMess against VLESS. The recommended setup applies when the server explicitly provides a TLS endpoint. If the configuration uses another security mechanism, check its parameters separately.
TLS endpoint: Enable verification and check SNI
RecommendedEnable TLS when required by the server, enter the SNI specified in the configuration, and leave certificate verification enabled. If you see a certificate error, first check the domain name, system time, and server certificate. Don’t routinely bypass verification.
Use when: Your service provider explicitly provides a TLS endpoint and the certificate matches the specified name
Non-TLS endpoint: Configure only as explicitly specified
Disable TLS only when the configuration explicitly says the endpoint does not use it. VMess protocol-layer encryption and TLS operate at different layers; the protocol name alone cannot establish whether a VLESS connection is secure overall.
Use when: The existing configuration explicitly specifies a non-TLS endpoint and explains how its security layer is handled
Decision: Check the name first when a certificate error occurs; don’t relax verification
Compare the SNI in the configuration with the value you entered, character for character, then check the date and time in system settings. If both are correct and the connection still fails, ask your service provider to check the server certificate.
Host and SNI may often use the same domain name, but they aren’t interchangeable. Host is part of the HTTP request; SNI is part of the TLS handshake. Failures can occur at different stages: if TLS fails, the WebSocket request that follows never gets a chance to complete.
Can’t connect after saving? Troubleshoot each connection stage
When the toggle is on in Home, the local VPN configuration has started working; this does not mean the remote server has authenticated the connection. A delay shown by Connectivity Test only means that the test returned a result. It does not by itself confirm that the UUID, WebSocket handshake, or all web requests are working. Follow the steps below in order, changing one group of settings at a time.
- Check the selected profile. Return to Home and check which profile is selected under SERVER. You may have edited a new profile while the old one is still being used.
- Check basic reachability. Run Connectivity Test. If it times out, first check Address, Port, and your current network. A timeout does not necessarily mean the UUID is wrong.
- Check authentication and transport. Recheck Type, UUID, VMess-specific options, or VLESS Flow, then check Transport, Host, and Path. Don’t change the protocol and transport at the same time.
- Check TLS. Check the TLS toggle, SNI, and any certificate errors. An incorrect device time can also interfere with validation and authentication, so correct it first.
- Rule out routing rules. Go to Home → Global Routing and temporarily select Proxy, then test the same destination using the selected profile. Proxy directs this test through the proxy path as much as possible. Restore the previous mode afterward; this won’t fix incorrect server fields.
- Restore your usual configuration. If Proxy works but Config doesn’t, open Config and check the active configuration and rule routing, including whether the request matches Direct or REJECT. If only domain-based access fails, check DNS instead of continuing to change the UUID at random.
Direct in Global Routing does not test whether the remote proxy is working. Config routes connections according to the selected configuration; with Scene, check the policy used by the active scene. If the connection keeps turning back on automatically, check the auto-connect conditions under Settings → On Demand. On Demand controls when the connection starts; it does not correct VMess or VLESS fields.
FAQ: Changing protocols, ports, and subscription updates
Why does the same UUID work with VMess but fail after I switch to VLESS?
A UUID is only part of the authentication details, and the two protocols use different handshakes. Return to Add Server and restore the Type specified in the original configuration. If you need to use VLESS, ask your service provider whether a separate VLESS endpoint is available and confirm its port, transport, and security settings.
If the Port is 443, do I have to enable TLS?
A port number does not specify the security settings. Open the current profile and check Port and TLS against the original configuration. Enable TLS only if the configuration explicitly requires it. Don’t combine a port from one profile with the TLS setting from another to create a new configuration.
The UUID looks right, but authentication still fails. What should I check first?
First, copy the complete UUID again and remove any leading or trailing spaces. Then check Type and the protocol-specific options. Next, check the device time and account status. Ask your service provider whether the account has expired or been disabled; the local form alone can’t tell you.
Why did my manual fix disappear after the subscription updated?
A subscription update may rebuild or overwrite profiles based on the remote configuration. Keep a separate manual profile for comparison, then update your own subscription and compare the fields one by one. If the remote fields remain incorrect, send the differences to your service provider with sensitive details removed rather than repeatedly overwriting the entire configuration.
To confirm the setup, make sure the intended profile is selected, the protocol matches the server, the transport and TLS fields are correct, and the actual destination works in a clearly specified Global Routing mode. A successful save, an enabled toggle, and a test showing latency each indicate a different stage; none proves the others. For basic steps, see the user guide. For DNS and rule routing, continue to Troubleshooting.