VMess and VLESS cannot be converted into each other by changing only the Type. Both may use a UUID, but their protocol-level encryption, alterId, and transport security work differently. This guide is for users who already have server settings and want to enter them manually in Shadowrocket: distinguish the protocol from TLS, check the address, port, credentials, and transport fields, then troubleshoot by changing one variable at a time.
Understand the three layers: protocol, transport, and TLS
In Shadowrocket, VMess or VLESS is the protocol type for a server entry. WebSocket and similar options describe how data is transported, while TLS handles encryption and authentication at the transport layer. These are separate settings. If your provider specifies “VLESS + WebSocket + TLS,” check each set of parameters separately; entering only VLESS and a UUID is not enough.
VMess provides protocol-level authentication and encryption, and its encryption option must be compatible with the server. VLESS does not encrypt the payload itself, and authentication is not the same as encryption. Common deployments pair VLESS with TLS or another transport security mechanism, but that does not mean every VLESS entry should use identical TLS settings.
| Check | VMess | VLESS |
|---|---|---|
| Credentials | Usually a UUID; it must match the server | Usually a UUID; it must match the server |
| Protocol-level encryption | Has a separate encryption setting; configure it to match the server | The protocol itself does not encrypt the payload |
| alterId | Legacy compatibility field; use 0 with modern AEAD configurations | Does not use VMess alterId |
| TLS | Can be used alongside protocol-level encryption; enable as required by the deployment | Commonly protects the transport; a UUID cannot replace it |
| Transport settings | Transport type, Host, Path, and other settings must match the server | Check each setting against the server; don't copy them from another entry |
The protocol name alone does not determine connection speed or availability. Two entries labeled VLESS may use different servers, ports, transports, and TLS settings. When troubleshooting, compare the full set of parameters rather than assuming one protocol name guarantees a faster connection.
UUID, alterId, and encryption: values you must not guess
A UUID identifies a user; it is neither a server address nor a nickname you can make up and use. The common text format is 36 characters including hyphens, with 32 hexadecimal characters. When copying, check for leading or trailing spaces, line breaks, and missing hyphens. Even a correctly formatted UUID will fail authentication if it does not match the identity registered on the server.
alterId is part of VMess's legacy design. Modern VMess AEAD configurations use alterId=0; don't change it to 16, 32, or 64 based on outdated guides. If your existing settings specify a nonzero value, confirm the current server requirements with your provider instead of treating an old value as a universal setting. VLESS has no VMess alterId field to copy.
VMess encryption and TLS are separate settings. If your parameters include auto, aes-128-gcm, or chacha20-poly1305, check which field each value belongs to and keep it as specified. “VLESS does not encrypt the payload” does not mean TLS should be disabled for every entry, and a VMess encryption option should not be entered as a VLESS setting.
How to check: verify the identity first, then the transport security
If the UUID format looks wrong, copy the original again. If the format is valid but the connection still fails, check Type, VMess alterId and encryption settings, and TLS status. Don't keep changing the UUID or disabling certificate verification to see what works.
Manual Add Server setup: basic fields first, then transport settings
Get the settings from your provider. If you have a complete subscription that can be imported, use the imported entry to check the fields; this is usually less prone to omissions than entering everything manually. Buying the client does not include a connectivity plan. This guide explains how to enter and check settings you already have; it does not provide connection credentials.
- Open the add screen. In Home, tap the add button in the upper-right corner to open Add Server. Set Type to VMess or VLESS. After changing the type, check the available fields again.
- Enter the connection destination. Enter the server domain or IP address in Address and the specified port in Port. Address should generally not include
https://, a path, or a port suffix. Use the port provided by your provider; don't change it to 443 just because TLS is enabled. - Enter the identity and protocol settings. Copy the UUID into the corresponding identity field. For VMess, also check alterId and the encryption setting; don't apply these VMess values to VLESS. Field labels may vary by protocol and interface language, so match them by meaning rather than position.
- Choose the transport. Set the transport type to match the supplied settings. For WebSocket, also check Host and Path. With other transport types, don't add WebSocket-specific fields just to fill every field.
- Check TLS. Enable or disable TLS as specified, and check Server Name / SNI, certificate verification, and any other required options. If the settings specify a protocol option such as Flow, keep its given value; don't add one yourself.
- Save and return to Home. Check the new entry's type and name, select it, and run a test. Don't overwrite your only working entry; keep the original so you can compare or restore it.
TLS, Host, and Path: the right domain in the wrong field can still fail
TLS does more than “turn on encryption.” Proper certificate verification also checks that the certificate is trusted, within its validity period, and matches the target name. If Address is an IP but the certificate was issued for a domain, your provider may give you a separate SNI. Keep each value in its intended field; don't copy the IP into every name field.
Check transport fields and TLS fields separately
WebSocket transport
- The transport type must match the server.
- Use the specified request hostname for Host; don't add a scheme prefix.
- Preserve the leading slash, letter case, and any existing query parameters in Path.
/wsand/WSare not interchangeable.
TLS security settings
- Match the TLS status to the supplied settings; don't infer it from the port number.
- Use the specified server name for SNI, usually without a path or port.
- Keep certificate verification enabled. If an error occurs, check the name and system time first.
- Enter additional settings such as ALPN only when they are explicitly provided.
Identify which layer is failing before changing its settings. If the TLS handshake fails, changing the WebSocket Path usually won't fix a certificate issue.
For example, if your settings specify Port 443 and WebSocket Path /ws, those are the values for that particular entry. This does not mean every VMess or VLESS configuration uses this combination. The port and path here illustrate field meanings; they do not form a working connection configuration.
Choosing encryption settings: keep the supplied values instead of guessing
When entering settings manually, it's easy to mistake “selectable” for “choose whatever you like.” The VMess encryption setting must be compatible with the protocol implementation and server requirements; TLS status must match the server endpoint. Don't choose an option because its name sounds stronger or faster. Reproduce the supplied settings accurately.
Encryption and TLS: keep the supplied values
RecommendedEnter the VMess encryption option as specified and match TLS status to the server endpoint. For VLESS, check transport security separately; don't reuse VMess encryption fields.
Best for: first-time manual setup, checking an imported subscription, or troubleshooting an entry with complete settings
Encryption and TLS: swapping options at random
Changing settings in the client alone does not change the server. Disabling TLS, changing the port, or switching protocol encryption at random can cause new handshake or authentication errors, so this is not a reliable troubleshooting method.
Best for: syncing settings only after the server parameters have explicitly changed and you have the corresponding new values
Rule of thumb: change only one confirmed incorrect field at a time
Record the original value first, then change it and retest the same destination. If you change Type, port, TLS, and Path all at once, even a successful connection won't tell you which change fixed the issue. It can also lead to mismatches the next time the subscription updates.
Still can't connect after saving? Check the failure stage
A normal latency reading does not mean the entire connection has authenticated successfully. Different tests may measure only whether a destination port is reachable, a connection is established, or a particular request gets a response. One number alone cannot confirm that the UUID, TLS, and transport settings are all correct. During testing, note observable differences: whether a connection can be established, whether a certificate error appears, and whether only certain websites fail.
- Make sure the new entry is selected. Check the current selection in Home to avoid testing the old entry. If needed, stop and reconnect, then send a new request.
- If the connection times out, check the destination first. Make sure Address and Port aren't missing characters or accidentally combined. Retest on another available network. If the port cannot be reached, don't assume the UUID is the cause.
- If you see a TLS error, check the name and time first. Confirm the device's system time is correct and SNI matches the supplied settings. An expired certificate or server configuration issue needs to be handled by your provider; skipping verification is not a suitable long-term fix.
- If the connection drops immediately after the handshake, check authentication and transport. Recheck the UUID, VMess alterId and encryption settings, and WebSocket Host and Path. A disconnect alone does not identify the cause; use any available connection error details to narrow it down.
- If only some requests fail, check routing. Open Home → Global Routing and check the current selection. Proxy can temporarily help rule out rule-matching issues, but you still need a valid connection entry. Direct cannot verify whether the entry's proxy connection works. Restore your original routing setting after testing.
Config manages settings such as rules; it cannot fix an incorrectly entered UUID. On Demand controls when a connection is triggered; it cannot fill in missing TLS settings. First get a single entry working under clear test conditions, then check automatic connections and rule-based routing to avoid changing several variables at once.
Manual setup FAQs: changing protocols, subscription updates, and redacting details
If the UUID is the same, can I change VMess directly to VLESS?
A matching UUID does not mean the protocols can be converted. They have different handshake and field requirements, and the server must provide an endpoint for the corresponding protocol. Get the complete VLESS settings from your provider and create a separate entry; don't just change Type on the original one.
VLESS has no protocol-level encryption. Does that mean I must enable TLS manually?
First check which transport security method the original deployment uses. Common VLESS configurations rely on TLS or another mechanism to protect the transport, but enabling TLS on the client alone cannot turn a non-TLS endpoint into a TLS endpoint. If the supplied settings don't specify transport security, ask your provider rather than guessing.
Why did my manual changes disappear after a subscription update?
A subscription update may overwrite entries managed by the subscription. In Home, distinguish subscription entries from manually created ones. To compare settings, create a separate entry and keep the original. If the subscription itself contains incorrect settings, ask your provider to check the source parameters rather than repeatedly editing them only to have an update overwrite your changes.
What should I hide before asking someone to check my settings?
Redact the full UUID, tokens in subscription links, passwords, and complete share links. You can share the Type, transport type, whether TLS is enabled, the observed error, and a redacted outline of the fields. Check again before posting publicly; QR codes may also contain complete credentials.
Check settings in this order: Type → Address and Port → UUID → protocol-specific fields → transport → TLS and name fields. If the original settings are incomplete, get the missing details first; don't combine a domain, path, or credentials from another entry. To review subscription import and management, read the subscription guide. If you're new to Shadowrocket, start with the beginner's guide for system authorization and basic connection checks.