In Shadowrocket, a share link typically contains one connection configuration, while a subscription URL points to a list of configurations that can be fetched again. This guide is for users who already have their own service configuration and subscription: identify the link type, check the protocol fields, then import, update and verify the connection. Domains, passwords and UUIDs shown here are examples only and cannot be used to connect.
First, tell connection parameters from a remote list URL
ss://, vmess://, vless:// and trojan:// are common prefixes for single share links. They generally specify which address to connect to, which protocol to use and how to authenticate. When imported, Shadowrocket can parse the server, port and authentication fields from the link. A successful import means only that the syntax was recognized; it does not mean the server is reachable or the account is valid.
A subscription URL usually starts with https:// and points to a remote address that must be requested. The response may contain multiple share links or Base64-encoded text representing those links. Regular web pages can also start with https://, so the prefix alone does not identify a subscription.
- Single share link: Imports a snapshot of the parameters at that moment. If they change, import the link again or edit the entry manually.
- Subscription URL: Saves the source of a list. Each update fetches its contents again, so entries may be added, removed or changed.
- Config file: Manages settings such as rules and policies. Do not assume that any Config file URL can be used as a node subscription URL.
ss://: Check the encryption method, password and address
A common Shadowsocks share link format is SIP002, which puts authentication information before @, followed by the server and port. The authentication section is usually URL-safe Base64-encoded method:password; query parameters and a remark after # may also be included. Older formats encode a longer section as a whole, so do not assume every link uses the same layout when parsing one manually.
ss://
Decoded authentication: aes-128-gcm:example-password
Server: example.com
Port: 8388
Remark: Example| Field | Meaning and what to check |
|---|---|
| method | For example, aes-128-gcm. It must match the server configuration; do not substitute a method just because its name looks similar. |
| password | Used for authentication; case-sensitive. Preserve the original value when copying, without adding spaces or line breaks. |
| host:port | Server address and listening port. 8388 is an example only; use your actual port. |
| Query parameters such as plugin | May affect the transport method. Check the imported result and current support; do not remove these parameters without checking. |
| Remark after # | Primarily helps identify the entry in a list. Changing the remark does not change the server address. |
Base64 is an encoding, not a security measure. Anyone who can decode the authentication fields can still read the password. If import fails, first check whether a chat app wrapped or truncated the link or added punctuation, then check the encoding and format. Do not start by changing the encryption method.
vmess://: Decode the JSON, then check the transport fields
A common VMess share link format places Base64-encoded JSON after vmess://. The example below shows the structure before encoding; it is not a complete share link you can paste to import. Fields vary by source, so do not overwrite your own configuration with this example.
{
"v": "2",
"ps": "Example",
"add": "example.com",
"port": "443",
"id": "00000000-0000-0000-0000-000000000000",
"aid": "0",
"net": "ws",
"type": "none",
"host": "example.com",
"path": "/example",
"tls": "tls"
}addandport: The connection address and port.psis a remark, not an address.id: The UUID authentication field. The all-zero value shown is for illustration only; use your own existing value.aid: The alterId field in legacy formats. Do not increase its value arbitrarily to try to make a connection work.net,hostandpath: This example describes WebSocket and its Host and path. Path casing, slashes and query strings may affect the connection.tls: TLS is enabled in this example. The server address, HTTP Host and TLS SNI serve different purposes and are not necessarily the same.
After importing, open the entry's edit screen and compare the server, port, UUID, transport method and TLS options with the original configuration. If the text decodes but the app cannot recognize it, the link may use a variant format or unsupported fields. Export a compatible format from your own original configuration source instead of simply changing the link prefix.
vless:// and trojan://: Similar formats, different authentication
Both formats often combine authentication information, a server, a port, query parameters and a remark, but their authentication fields mean different things. VLESS typically uses a UUID; Trojan typically uses a password. The examples below show field positions only; the domain and authentication values are fictitious.
vless://[email protected]:443?encryption=none&security=tls&type=ws&host=example.com&path=%2Fexample&sni=example.com#Example
trojan://[email protected]:443?security=tls&type=tcp&sni=example.com#Example| Field position | VLESS | Trojan |
|---|---|---|
| Before @ | Usually a UUID | Usually a password with the necessary URL encoding |
| security=tls | TLS is used in this example; other configurations may use different security settings | TLS is used in this example; it must match the server configuration |
| type | This example uses ws; check both Host and path | This example uses tcp; do not copy ws parameters |
| sni | Server name used for the TLS handshake | Server name used for the TLS handshake |
encryption=none is a VLESS protocol parameter in this example; it does not mean the entire connection lacks TLS. Decoding path=%2Fexample gives /example. Characters such as @, # and & in a password, path or remark must be encoded correctly for their position, or they may be parsed as separators.
Importing and updating: Use the right flow for each link type
First, make sure the clipboard contains only the complete link, with no surrounding explanatory text. In Shadowrocket, Home displays connection entries, Config manages configuration files and Settings contains app preferences. Both single share links and Subscribe can result in selectable entries in Home, but they are maintained differently afterward.
Two import flows: single parameters and Subscribe
If you have a single share link
- Copy the complete ss://, vmess://, vless:// or trojan:// link.
- Return to Home. If an import prompt appears for the clipboard contents, review and import them, then allow access if prompted by the system.
- If no prompt appears, use the relevant import option, or go to Home → +, choose a protocol and enter the fields from your original configuration.
- After saving, open the edit screen and check the address, port, authentication and transport parameters.
If you have a subscription URL
- Go to Home → + → Type, then select Subscribe.
- Paste your complete subscription URL in URL, add a recognizable remark, then save.
- Fetch the contents for the first time, expand the relevant group to check its entries, and update the subscription when you need to sync it.
- After updating, check the selected entry again, especially if the source has removed or replaced items.
A single link saves parameters; Subscribe retains the remote list source. Before editing an entry from a subscription, note its original values: the next update may overwrite local changes.
A subscription URL may look like the example below. It is illustrative only and cannot be used to fetch configurations. Real URLs often contain access credentials in the query string or path; preserve them in full, and do not post them publicly or submit them to an unfamiliar conversion site.
https://example.com/sub?token=xxxx- Request timed out: Check whether the current network can reach the subscription URL, and distinguish DNS resolution failures from connection failures and HTTP response errors.
- Received 401 or 403: Check that the credentials in the URL are complete and confirm access with your original configuration source. Re-importing the same URL repeatedly will not usually resolve a permissions issue.
- Request succeeded but no entries appeared: Confirm that the response contains subscription data, not a login page, error page or regular web page. A successful status code does not guarantee valid content.
Verify after import: Separate parameter issues from routing issues
Once an entry appears in Home, you still need to verify the connection. Check the parameters first, then confirm the Global Routing mode, and finally observe the connection result for the target request. A subscription updates connection entries; it does not necessarily provide a complete set of routing rules. Whether rules take effect also depends on the current Config and routing selection.
Global Routing → Config
RecommendedWith rules already in place, follow the policy set by the current Config. Rules such as DOMAIN-SUFFIX, GEOIP and IP-CIDR, together with the FINAL fallback, determine the outcome. Unmatched requests do not necessarily go direct.
Best for: Checking that everyday rules and connection entries work together after import.
Global Routing → Proxy
Routes connections handled by the app through a proxy, temporarily reducing rule-based routing as a factor during troubleshooting. Make sure the correct, working connection entry is selected.
Best for: Briefly distinguishing a proxy connection failure from a Config rule-matching issue.
Global Routing → Direct
Provides a direct-connection comparison. If a webpage opens in this mode, that does not prove the imported proxy parameters work or that subscription entries are usable.
Best for: Checking direct connectivity on the current network as a troubleshooting baseline.
Bottom line: Compare routing with the same entry first
Keep the network and selected entry unchanged. Temporarily switch from Config to Proxy, then test the same destination. If only Config fails, check the matched rule and destination policy first. If both fail, recheck authentication, transport parameters and server reachability. Restore the original routing mode when testing is complete.
Global Routing also includes Scene; do not mistake it for a fourth share link format or protocol. Settings → On Demand manages connections triggered by conditions; it does not convert share links into subscriptions. Note the original settings while troubleshooting to avoid changing multiple variables at once and obscuring the cause.
FAQ: What to check after a link is recognized
Can I change vmess:// to vless:// and use the link as is?
No. The two formats have different share structures, authentication and transport requirements. Get a complete configuration for the relevant protocol from your own original configuration source, then import and check its fields. Changing only the prefix may cause parsing to fail or create an entry that does not meet the server's requirements.
Why did my manually changed port revert after refreshing the subscription?
A subscription update may rebuild or overwrite entries using remote data. First check the original port returned by the subscription. If you need to keep a local change, create a separate entry and label it clearly; note that it will no longer sync automatically with the original subscription.
The import succeeded. Why can't I connect?
In Home, open the entry's edit screen and check the server, port, password or UUID, TLS, SNI and transport parameters in turn. Then compare Global Routing as described in the previous section. A link that parses correctly only has readable fields; it does not verify the status of the remote service.
Does scanning a QR code import different content from copying a link?
A QR code is just a way to carry text. If the scanned result is a single protocol link, handle it as a single configuration; if it is a subscription URL, use Subscribe. Identify the content type before saving. Scanning a code does not mean the content will update automatically.
Can I send someone a screenshot of the full link for troubleshooting?
First redact passwords, UUIDs, subscription tokens and identifiable account information. Keep only the protocol, error message and necessary transport fields. Base64 text may also contain authentication information. If credentials have already been exposed publicly, revoke or replace them through your own original configuration source.
To organize entries, see Managing subscriptions and connection entries. For initial setup and system permissions, see the user guide. This article explains how to use configurations you already have; it does not cover providing or choosing connection services.