First determine whether a link contains server settings or points to a server list, then choose the appropriate import method. This guide is for users who already have links from their own service provider and want to verify the import in Shadowrocket. Learn to identify four URI formats, find the subscription option, and troubleshoot import or update failures by checking individual fields. Steps are based on the iPhone / iPad interface; other platforms may differ.
Check the prefix first: single-server URIs vs. subscription URLs
ss://, vmess://, vless:// and trojan:// typically contain the parameters for a single server entry. Copy the entire link and the client parses the address, port, authentication and transport settings locally. A parsed entry does not mean the connection succeeded or that the server is currently available.
A subscription link is usually an https:// URL. Shadowrocket accesses the URL, reads the response and creates or updates a server list. The URL may contain an access token; it is not an ordinary public webpage or a proxy protocol. An HTTPS prefix alone does not prove that a URL is a subscription—confirm its purpose and response format.
In short: identify the content, then choose an import option
If you see a protocol prefix, treat the link as a single-server entry. Use Subscribe only for an address clearly identified by the provider as a subscription URL. Don’t put a subscription URL’s domain in the single-server Address field or use a full protocol URI as a subscription URL.
ss://: authentication may be Base64-encoded
ss:// is used to share Shadowsocks configurations. The common SIP002 format places the encryption method and password in the user information, followed by the server address and port; the user information is typically encoded with URL-safe Base64. Older formats may Base64-encode the authentication details, address and port together, so a server domain that isn’t immediately visible doesn’t mean the link is incomplete.
| Component | How to check |
|---|---|
ss:// | Identifies the Shadowsocks sharing format, not a subscription update URL. |
| User information | After decoding, this usually contains the encryption method, a colon and the password. Base64 does not provide encryption. |
| Server and port | For example, node.example.com:8388 is a sample address; 8388 is not a fixed port. |
?plugin= | Optional plugin parameters. Don’t assume the client supports every plugin, and don’t delete them just to make the link import. |
Content after # | Usually a remark or display name. Spaces and non-ASCII characters may be percent-encoded. |
After importing, open the entry’s edit screen from Home and check Type, Address, Port, encryption method and Password. Match the encryption method and password to their respective fields; don’t paste the entire Base64 string into Password. If the original link is missing characters, copy it again from the source instead of guessing from its encoding.
vmess://: distinguish encoded JSON from other share formats
A common vmess:// link uses a prefix followed by a Base64-encoded JSON object. The decoded JSON typically includes fields such as add, port, id, net and tls. Sharing formats can vary by generator, so don’t assume every VMess link has the same outer structure.
The JSON below is a field reference, not a working server or a complete link you can import. The domain is an example, and the UUID is all zeros for demonstration. Only the corresponding values from an actual service configuration can be used to connect.
{
"v": "2",
"ps": "Example",
"add": "node.example.com",
"port": "443",
"id": "00000000-0000-0000-0000-000000000000",
"aid": "0",
"scy": "auto",
"net": "ws",
"type": "none",
"host": "edge.example.com",
"path": "/demo",
"tls": "tls",
"sni": "edge.example.com"
}
addandportspecify the connection target. Port 443 is commonly used for TLS, but the port number alone does not confirm that TLS is enabled.idis the UUID used for authentication; don’t substitute a token from a subscription URL.- When
netisws, check the WebSocket Host and Path as well as the address and port. tlsandsnirefer to the TLS setting and the server name used during the handshake. Host, SNI and the connection address may differ.
If the link parses and displays a name but the connection fails, missing transport settings may be the cause—not an incorrect name. Don’t ignore Host, Path or TLS just because Address is correct. Don’t change ws to another transport unless you can confirm the original settings.
vless:// and trojan://: similar format, different authentication fields
Both link types commonly use a URI structure with user information, an address, a port and query parameters. VLESS usually uses a UUID as user information; Trojan usually uses a password. Changing the prefix alone does not convert one into the other. The examples below show structure only: the sample domain, all-zero UUID and demonstration password cannot be used to connect.
vless://[email protected]:443?encryption=none&security=tls&type=ws&host=edge.example.com&path=%2Fdemo&sni=edge.example.com#Example
trojan://[email protected]:443?security=tls&type=tcp&sni=edge.example.com#Example
| Field | Meaning and what to check |
|---|---|
Before @ | Usually a UUID for VLESS or a password for Trojan. Special characters must be encoded according to URI rules. |
security=tls | Indicates TLS-related settings. These must match the actual service; don’t infer them from the port alone. |
type=ws / type=tcp | Specifies the transport. Each transport may require different additional fields. |
sni | The server name used in the TLS handshake. It should match the service configuration and certificate requirements. |
host / path | Commonly used for WebSocket settings; %2Fdemo decodes to /demo. |
encryption=none describes VLESS’s own encryption field; it does not mean the entire connection is necessarily unencrypted. Check TLS separately. Trojan typically uses TLS for transport. If you encounter a certificate error, check the device time, SNI and certificate; disabling certificate verification should not be a routine fix.
Support for extended parameters can vary between parsers. If a link includes parameters not covered here, preserve the original and check the edit screen. A successful import does not guarantee that every extended parameter took effect.
Scan, clipboard or Subscribe: choose based on link type
A QR code is simply another way to carry text. It can contain a single-server URI or a subscription URL; scanning doesn’t turn a single-server link into an updatable subscription. Check the source’s description first, then review the scanned result.
Subscribe: keep the subscription up to date
RecommendedIf you already have a subscription and need to keep it updated, go to Home → + → Type, choose Subscribe, enter the subscription URL in the fields shown and save. After the first successful fetch, check the generated entries and subscription group.
Best for: a confirmed subscription URL that keeps your own server list in sync
Clipboard import: parse a complete URI
Copy the entire text, from the protocol prefix through the final remark, then return to Home. If prompted to access the clipboard or import the link, confirm and check the parsed result. If no prompt appears, use + to create an entry manually with the original parameters.
Best for: one or more complete single-server links in text form
Scan: read the original content from a QR code
Use the scanner from Home, allow camera access and scan the QR code. If the result is a webpage or ordinary text, confirm what it is for before saving it as a server entry.
Best for: a link displayed on another screen that’s difficult to copy by hand
A subscription URL might look like https://example.com/sub?token=xxxx. This is only an example of the URL format, not a working link. Keep the token in the query string intact; don’t replace it with a single-server password or share a URL containing a token in a public forum.
- Save your existing entries and settings first so you don’t lose the original configuration while troubleshooting.
- After importing, check the number of entries, Type, Address, Port, TLS and transport settings.
- Use the in-app update option for the relevant subscription. Confirm that it updates successfully before considering automatic updates.
- If you edit an entry managed by a subscription, a later update may overwrite your changes with the parameters returned by the server. Make a separate note of any changes you need to keep.
A subscription response may contain a set of share URIs or another format recognized by the client. A server-list subscription and a configuration file in Config are different things. Importing servers does not automatically configure your rules, DNS or Global Routing.
Troubleshoot import, subscription and connection failures separately
Start by identifying when the problem occurs. If no entry is created, check the link format first. If the entry exists but the subscription won’t update, check the URL request. If you can select an entry but webpages won’t load, check the connection and routing. Don’t repeatedly delete all configurations before identifying the failing stage.
Why wasn’t the copied link recognized?
Make sure the text starts with a prefix such as ss:// and doesn’t include quotation marks, explanatory text or line breaks added by a messaging app. Check that you copied the full link, not just its displayed text. If clipboard access was denied, check the app’s paste permission in system settings, or go to Home → + and enter the known parameters manually.
The QR code contains an https:// URL. Can I use it as a server?
The prefix alone isn’t enough to tell. First confirm whether it’s a subscription URL, a configuration URL or an ordinary webpage. Only use a URL explicitly intended for a server list in an entry with Type set to Subscribe. If the scanned preview doesn’t match the source’s description, don’t save it yet.
The subscription saves, but its update fails. What should I do?
Saving only creates a local entry; it doesn’t confirm that the remote request succeeded. Check that the URL is complete, the token is still valid and the address is reachable. HTTP 401 or 403 errors usually indicate an authorization issue; 404 points to a path or resource problem; a timeout calls for checking the network and server response. Changing a single-server Port won’t fix a subscription request error.
The server imported successfully. Why won’t webpages load?
On Home, check the selected entry and connection status, then review Global Routing. Direct does not send traffic through the selected proxy. Proxy can help isolate rule-related issues temporarily; Config applies the current configuration. Note the original mode and restore it after testing. Also check Address, Port, authentication, TLS, SNI and transport settings.
Settings → On Demand manages connections triggered by conditions; it doesn’t repair an invalid share link. When troubleshooting an import, first verify one entry manually and test its connection. Then check On Demand separately so automatic connection behavior doesn’t get confused with link-format issues.
Before sharing: encoded links are not redacted
Base64, percent encoding and QR codes do not protect authentication details. A share link may contain a password, UUID and server address; a subscription URL may contain a token that grants access to the entire list. Even if a screenshot doesn’t show the password in plain text, a QR code or encoded string may still be decoded.
- When asking for help, share only what’s needed, such as the protocol, transport, port and error message.
- Remove the full password, UUID, subscription token and QR code. Hiding only the remark is not enough.
- To illustrate the structure, use an example domain and clearly marked sample values. Don’t paste a real link.
- If credentials have been exposed, revoke or replace them through your own service management channel, then update the local entry.