This guide is for users who already have their own provider configuration or subscription and need to identify and import links in Shadowrocket. First, distinguish a single-server link from a subscription URL. Then check encoding, authentication, and transport fields. Finally, tell import errors apart from subscription update and connection failures. All domains, passwords, UUIDs, and tokens shown here are fictional and cannot be used to connect.
1. First, Know the Difference: A Share Link Contains Connection Parameters; a Subscription URL Provides Updates
Shadowrocket can parse the parameters in a share link and turn them into a connection entry. Text beginning with ss://, vmess://, vless://, or trojan:// usually describes a server's protocol, address, port, and authentication details. Some formats also include TLS, transport, and remarks. These links are not ordinary web addresses to open in a browser.
A subscription link is usually an HTTPS URL. The client requests content from that address and adds supported connection entries from the response to the associated subscription. It provides a reusable way to retrieve a list; the URL itself does not contain every connection detail. An https:// prefix alone does not confirm that a URL is a subscription—it could lead to a login page, an error page, or an ordinary information page.
| What to check | Single share link | Subscription link |
|---|---|---|
| Main contents | Parameters for one connection entry | Remote URL for retrieving a connection list |
| Import process | Primarily parses text locally | Requests the URL and parses the response |
| What changes later | The original share-link text does not change on its own | Updates can retrieve changes to the remote list |
| Sensitive information | Password, UUID, and server details | Token in the URL and returned configuration |
A single share link is not the same as a complete .conf configuration file. Importing a server usually does not replace items such as [Rule] or [Host] in Config. The server determines where to connect; rules determine how requests are handled. Check them separately.
2. ss://: Identify the Encoded Shadowsocks Authentication
ss:// is a common prefix for Shadowsocks share links. A common SIP002 format combines the encryption method and password as method:password, then places the Base64URL-encoded result before @. The server address and port remain readable. Decoding the authentication section below gives aes-128-gcm:password; the password is for demonstration only.
ss://[email protected]:8388#Demo-SSss://: Indicates that the link should be parsed as a Shadowsocks share link.YWVzLTEyOC1nY206cGFzc3dvcmQ: Encoded encryption method and password. The example omits the trailing Base64 padding.example.com:8388: Server address and port. Do not replace the port with a more commonly used number when importing.#Demo-SS: A remark, not a connection password; it does not change the server's region.
Some older share links encode a longer string—including the server address—as a single Base64 value, so the presence or absence of @ is not a reliable test on its own. Links with plugin parameters may also include a query string. If the source configuration requires a plugin or additional transport parameters, do not remove them just to shorten the text.
3. vmess://: Decode the JSON, Then Check Each Field
A common vmess:// share format encodes a JSON string as Base64 and appends it to the prefix. The decoded result should be valid, complete JSON—not HTML from a web page. The example below illustrates the fields; it is not a complete link you can paste to import.
{
"v": "2",
"ps": "Demo-VMess",
"add": "example.com",
"port": "443",
"id": "00000000-0000-4000-8000-000000000001",
"aid": "0",
"scy": "auto",
"net": "ws",
"type": "none",
"host": "example.com",
"path": "/demo",
"tls": "tls",
"sni": "example.com"
}| Field | Example meaning | What to check |
|---|---|---|
add / port | Server address and port | Do not confuse these with HTTP Host or SNI |
id / aid | UUID and alterId | Authentication parameters must match the existing server configuration |
net / path | WebSocket transport and request path | The capitalization and slashes in /demo are part of the configuration |
host / sni | HTTP Host and TLS Server Name | They may match, but serve different purposes |
ps / v | Remark and share-format identifier | v is not the Shadowrocket version number |
VMess share links generated by different sources may have different fields. The presence or absence of a single field does not prove that a service will work. After importing, open the entry's edit screen and check that the authentication, transport, and TLS settings were parsed correctly. Seeing a name only means the client read some of the information; it does not mean the server accepts those parameters.
4. vless:// and trojan://: Readable URI Fields Do Not Mean Unencrypted Transport
These link types often use a recognizable URI structure: authentication details come before @, the server comes after it, and query parameters describe transport or security settings. How readable the fields are has nothing to do with whether the connection uses TLS. Both examples below use fictional authentication details and reserved example domains.
vless://[email protected]:443?encryption=none&security=tls&type=ws&host=example.com&path=%2Fdemo&sni=example.com#Demo-VLESS
trojan://[email protected]:443?security=tls&type=tcp&sni=example.com#Demo-Trojan- The VLESS example uses UUID authentication.
encryption=nonedescribes a protocol field; it does not disable TLS specified in the query parameters. - In the Trojan example,
demo-passwordis the password andsni=example.comspecifies the TLS Server Name. type=wsandtype=tcpspecify different transport types; you cannot convert between them by changing only the prefix.path=%2Fdemodecodes to/demo. Percent-encoding represents special characters in a URI; it does not securely encrypt a password.
If a password contains delimiters such as @, #, or ?, the link generator must percent-encode them correctly. If you assemble a link manually and miss the encoding, the client may interpret part of the password as the server, a query parameter, or a remark. Also, do not encode an already encoded %2F again as %252F, or the path may no longer have its original value.
How to check: Compare parsed fields after import instead of guessing compatibility from the prefix
Check the server, port, and authentication first, then check transport and TLS. When a link includes extra security parameters or specific transport options, follow the client's parsed result and the server's requirements. Do not try to “fix” a link by deleting unknown fields or disabling certificate verification.
5. Importing and Updating Subscriptions: Keep the Source; Don't Treat Local Edits as Remote Configuration
The address below is clearly fictional and illustrates only the URL format: the path identifies the subscription endpoint, while a token in the query string often identifies access permissions. The path, parameter names, and response format of a real subscription depend on the provider the user already has.
https://example.com/sub?token=xxxxA subscription response may be a text list of supported share links or a Base64-encoded version of that text. A URL that returns a successful status but serves a login page still cannot be imported as a valid connection list. A QR code is simply another way to carry text: whether it contains a single share link or a subscription URL depends on the encoded content.
- Copy the full subscription URL you already have. Avoid including a period, quotation mark, or line break from surrounding chat text. Keep the original token unchanged; do not add to or edit it.
- In Home, tap
+in the upper-right corner to open the new entry screen. ChooseType → Subscribe, enter the address inURL, add a source label inRemarks, and save. - After the first fetch completes, return to Home and check the subscription and its entries. Open an entry's edit screen and confirm that its type, address, port, and authentication fields are populated.
- To refresh, use the update action for the relevant subscription in Home. After updating, check whether the entry list changed, then test the connection. An “update successful” message does not mean every server in the list is usable.
Management: Keep the Remote Subscription Separate from Local Test Copies
Keep the remote subscription
- Save the original URL and a note about its source.
- Use the update action to receive changes to entries and parameters.
- Before updating, note any custom changes you need to keep.
Maintain test entries separately
- If you need to try a change, create a separate entry with a clear remark.
- Change just one parameter at a time so you can compare the results.
- When testing is done, confirm which entry is selected in Home.
Subscription updates may overwrite or recreate entries from the source. Do not count on temporary edits to entries in a subscription being preserved.
6. After Import: Use Global Routing to Separate Connection Issues from Rule Issues
Home manages connection entries and the current selection, Config is for configuration files, and Settings is for client settings. If a web page still will not load after importing a single link, do not assume the link format is wrong: the request may not be using the newly imported entry, or the current rules may assign it to another policy. First note the current selection in Home, then check Global Routing.
Config
RecommendedApplies policies according to the rules in the current configuration. For everyday use with an existing ruleset, check both the matched rule and the policy it references—not just the selection in Home.
Best for: Using an existing rules configuration to handle requests according to its rules.
Proxy
Routes requests handled by the client through the proxy posture, which can help you compare behavior with the current connection. This does not guarantee that all device traffic is covered. Restore the previous posture after testing.
Best for: Briefly checking whether rule-based routing is affecting test results.
Direct
Uses a direct-connection posture, so it is not suitable for testing a newly imported proxy server. A web page loading in this mode does not prove that the share link's authentication parameters are correct.
Best for: Comparing direct-connection behavior on the current network.
Global Routing also includes Scene for switching between scenarios. Its behavior depends on the existing scene settings. It is not a new protocol and does not replace server authentication. If automatic connection conditions are configured, also check Settings → On Demand so an automatic reconnect is not mistaken for an unsaved import.
- First, verify parsing: can you see the correct server, port, and protocol on the entry's edit screen?
- Next, verify the connection: with network access available, test the target request using the currently selected entry.
- Finally, verify routing: restore Config and check which rule and policy the request actually matches.
7. Common Questions: Troubleshoot by Failure Stage Instead of Rewriting Links Repeatedly
Why didn't my ss:// link import?
First, check that the text starts with ss:// and that the messaging app did not insert line breaks, spaces, or an ellipsis. Then check that the encoded content is complete. Do not copy a shortened on-screen preview. If an entry appears after import but the connection fails, investigate authentication and network access instead of repeatedly trying different numbers of Base64 decodes.
Why is the list empty when the subscription URL opens in a browser?
A page loading only means you received some kind of response. Confirm that the URL is the subscription endpoint provided by a service you already have, not an account management page. Check that the token is complete and whether access needs to be authorized again. If the response is a login page or error message, resolve the URL or access issue first; do not turn the page contents into a share-link prefix and force an import.
A subscription update timed out. Should I add all the entries again?
Keep the existing configuration for now and confirm that the current network can reach the subscription URL. If the URL really does need to be accessed through an existing working connection, check Settings → Subscribe for Update via Proxy, then return to Home and try again. Authentication errors or an expired token are not network timeouts; changing the access route does not replace obtaining valid authorization.
Can I convert VMess to VLESS by changing vmess:// to vless://?
No. Common VMess share links contain Base64-encoded JSON, while common VLESS share links use a URI structure with a UUID, server, and query parameters. Their authentication and protocol behavior differ too. Get the complete configuration for the corresponding protocol from a provider you already use, then add it in Home and check its parameters. Replacing just the first few characters will not convert it.
Is hiding the password enough when sharing a screenshot of a link for troubleshooting?
No. A UUID, subscription token, QR code, or encoded authentication string may also grant access. When reporting a problem, describe the protocol, port, transport, and failure stage in text, and remove the full link. If real credentials have already been exposed, replace or revoke them through the original service's management channel, then update the saved details in the client.
Keep troubleshooting in a clear order: check whether the original text is complete, whether it parsed correctly, whether the remote request succeeded, whether authentication matches, and whether the rules apply the expected policy. Change one condition at a time and record what changes. This makes the cause easier to find than rebuilding a subscription, switching protocols, and changing rules all at once.