In Shadowrocket, an individual share link carries a set of connection parameters, while a subscription points to a remotely hosted list that can be updated. This guide is for users who have obtained connection details from their own service provider and want to import them or troubleshoot recognition issues. Identify the link type from its prefix, check the encoding, address, credentials, and transport settings, then verify a successful import separately from a successful connection.
1. Identify individual share links and subscription URLs
ss://, vmess://, vless://, and trojan:// are common protocol prefixes for individual connection profiles. They carry a server address, port, credentials, and sometimes transport settings. Turning the text into a QR code only changes how it is shared; it does not turn an individual link into a subscription.
A subscription is usually an https:// URL. Shadowrocket requests that URL, retrieves the list returned by the server, and parses its entries. The list can change even if the URL stays the same. An HTTPS URL is not necessarily a subscription: a regular webpage, sign-in page, or error page is not a list of connection profiles.
2. ss://: Check what the Base64 string encodes
A common Shadowsocks sharing format, SIP002, places a Base64-encoded method:password after ss://, followed by @ and the server address and port. In the example below, decoding YWVzLTEyOC1nY206dGVzdA gives aes-128-gcm:test.
ss://[email protected]:8388#Demo%20SSaes-128-gcmis the encryption method and must match the server configuration. Do not substitute another method just because its name looks similar.testis a sample password for this example; it is not a UUID or subscription token.example.com:8388specifies the server and port. 8388 is just an example; use the values provided by your service provider.#Demo%20SSis a remark;%20represents a space. Changing the remark will not fix an incorrect address or password.
An older format encodes the entire method:password@host:port string, so do not assume that every Base64 string should be decoded only up to the @. Some links also include a plugin query parameter. The plugin name and its options are part of the connection details, so do not truncate anything after the question mark.
Base64 and URL percent-encoding are separate layers. Base64 may contain +, /, and a trailing =; URL-safe Base64 uses a different character set. Do not replace every + with a space or add a fixed number of equals signs to every link. Start with the complete original text and let the importer handle the format.
3. vmess://: The encoded content is usually JSON
A common VMess share format consists of vmess:// followed by a Base64-encoded JSON object. Unlike the format in the previous section, decoding it usually produces structured data with named fields, not a single line of “password plus address.” The decoded result below is for illustration; it is not text you can paste as a share link.
{
"v": "2",
"ps": "Demo VMess",
"add": "example.com",
"port": "443",
"id": "11111111-1111-4111-8111-111111111111",
"aid": "0",
"scy": "auto",
"net": "ws",
"type": "none",
"host": "example.com",
"path": "/demo",
"tls": "tls",
"sni": "example.com"
}| Field | What to check |
|---|---|
add / port | The actual server and port. The port must be a valid number, with no full-width colon. |
id / aid | UUID and Alter ID. Use the server-provided values; do not treat the UUID like an ordinary password and change it freely. |
net / host / path | Transport type and related parameters. Preserve the slashes and capitalization in a WebSocket path. |
tls / sni | TLS settings and server name. A port of 443 alone does not determine these values. |
In the example, v is a field in the share format, not the Shadowrocket app version. Different generators may produce different sets of fields, so do not assume that every missing field can use the same default. After importing, open the profile details and compare the UUID, transport, TLS, and path with the original information. A correct remark and address are not enough to confirm that the other parameters are correct.
4. vless:// and trojan://: Similar structure, different credentials
Both formats commonly show the address and port after @, with query parameters specifying security or transport settings. Similar-looking links do not mean the protocols are interchangeable: in particular, a VLESS UUID cannot be used in place of a Trojan password, or vice versa.
vless://[email protected]:443?encryption=none&security=tls&type=ws&host=example.com&path=%2Fdemo&sni=example.com#Demo%20VLESS
trojan://[email protected]:443?security=tls&type=tcp&sni=example.com#Demo%20Trojan- VLESS: The value before
@is usually a UUID.encryption=nonespecifies the encryption parameter for VLESS; it does not mean the transport has no TLS. In this example,security=tlsspecifies TLS separately. - Trojan: The value before
@is the password. If it contains reserved characters such as@or#, they must be percent-encoded correctly. Otherwise, the parser may mistake part of the password for an address or remark. - Check both:
snispecifies the TLS server name. In a WebSocket setup,hostusually specifies the HTTP Host header. They mean different things and should not both be replaced with the server IP. - Decoding the path:
path=%2Fdemorepresents the path/demo. Decode only what is necessary and do not decode it repeatedly; that could change the meaning of characters that belong to the path.
These examples cover common formats, not every possible transport combination. If the original link includes extra parameters, keep it intact and check whether the current client can map them to the corresponding options. Do not delete unfamiliar parameters just because the link imported without an error, and do not disable certificate verification instead of checking the SNI, system time, and certificate configuration.
5. Import from Home, then manage profiles and rules separately
Individual links and subscriptions are maintained differently. An individual link usually creates a standalone profile; a subscription retains its link to a remote list. Updating a subscription may add, remove, or recreate profiles, so local changes to a subscribed profile should not be treated as permanent server-side settings.
- Get the complete original text from your service provider. First determine whether it is an individual protocol link, a QR code, or a subscription URL. Do not copy explanatory text, quotation marks, or ellipses from a chat message.
- For an individual link, use the client’s clipboard import option; for a QR code, use the scanner. After importing, return to
Homeand check for the new profile. - Add a subscription URL under
Home → + → Type → Subscribe. Enter the full URL and a recognizable remark. Menu layouts may differ by platform; select the subscription type with the same name. - After updating the subscription, check the number of profiles and any error messages. The example URL
https://example.com/sub?token=xxxxillustrates URL structure only; it does not provide a working list. - Open the profile details to verify its parameters, then select the profile you want to use and connect. Manage rules separately in
Config; a regular profile list is not a complete rules configuration.
When testing a connection, also check Global Routing. It affects whether requests use the selected profile, but it cannot fix incorrect parameters in a share link. The comparison below covers Shadowrocket’s routing modes; the recommended option is for everyday use with rules already configured.
Config
RecommendedRouting follows the rules in the current configuration. Check the request log to see whether a request actually matched PROXY.
Best for: verifying everyday rule-based routing when rules are already configured
Proxy
Route traffic handled by the client through the proxy. This helps temporarily rule out the possibility that a request missed the rules.
Best for: checking the connection of an imported profile on its own
Direct
Use a direct connection. If a webpage opens in this mode, that does not prove the imported profile’s proxy connection is working.
Best for: comparing against a direct connection on your local network
Takeaway: test one layer at a time
First confirm that the profile parameters are complete. Then temporarily use Proxy to test the connection, and finally switch back to Config to check which rules match. This separates parsing issues, connection failures, and routing results—and avoids changing multiple settings at once and losing track of the cause.
6. If a link is not recognized, check the text, encoding, and response in order
“Link not recognized” and “connection timed out” happen at different stages. The first occurs while parsing the text or subscription content; the second usually occurs after the parameters have been retrieved and a connection attempt has started. Note when the error occurs before deciding whether to copy the details again or check the network and server settings.
Copied a link, but no profile appeared to import?
Paste the original text into a plain-text editor and check that it starts with the complete protocol prefix, has no chat punctuation at the end, and contains no line breaks or spaces that cut off the content. If you only have a screenshot of a QR code, scan it instead of copying the image filename.
The decoded vmess:// content looks garbled. What should I change?
First make sure you copied the complete Base64 string, and distinguish standard Base64 from URL-safe Base64. Do not repeatedly URL-decode the entire string. A common JSON format should reveal fields such as add, port, and id after decoding. If the content is incomplete, get the original link again instead of guessing at the missing UUID.
The subscription URL opens in a browser. Why does the update still fail?
A browser may show a sign-in page, verification page, or error page instead of returning a list. Check that the full query string is intact. If the response shows 401 or 403, ask your service provider to confirm your access credentials and permissions; if it shows 404, check that the path is valid. Do not paste webpage text as a list of profiles.
The import succeeded, but the connection failed. Could the encoding be wrong?
First check the server address, port, password or UUID, then verify the TLS SNI and the WebSocket Host and path. For a certificate error, check the system time and certificate name; for a timeout, check network reachability and service status. Successfully parsing the encoding does not mean the server will accept those parameters.
Why did my remark or settings change after updating the subscription?
An update may recreate profiles from the list on the server. Compare the profiles with the current details from your service provider to confirm that the changes came from the remote list. If you need to keep local changes, distinguish standalone profiles from subscription profiles and avoid selecting outdated details from one of several copies.
After troubleshooting, report only the protocol name, the stage where it failed, and an error message with sensitive details removed. Server addresses, UUIDs, passwords, subscription tokens, and QR codes may grant access. To show the format, use the approach in this guide: keep the field names and replace the actual values. Share complete connection details only through a controlled channel when necessary.