If you already have a provider and subscription, first distinguish a subscription URL from a single-server share link. Use Subscribe for a list that needs periodic updates, Add Server to enter one connection manually, and a QR code or clipboard to read the content—neither determines whether the imported item can be updated. This guide focuses on Home on iPhone and iPad, covering the entry points, field checks, updates, and connection tests. On other platforms, follow the interface shown there.
Identify the content first: a subscription URL is not a server address
Shadowrocket needs connection details to establish a proxy connection. Get subscriptions from your provider; obtaining the app and purchasing a provider's service plan are separate matters. When you receive a string of text, don't immediately paste it into the server's Address field. First determine whether it's a subscription URL, a protocol share link, or a web page address that includes login or help text.
A subscription URL typically fetches a set of connection details over HTTPS. A single-server share link encodes the protocol, authentication parameters, and server information in a text string. An HTTPS prefix alone doesn't tell you whether an address is a subscription: provider dashboards, help pages, and login pages may also use HTTPS.
| Content received | How to identify it | What to do |
|---|---|---|
| Subscription URL | Explicitly labeled as a subscription by the provider; often includes authentication parameters | In Add Server, set Type to Subscribe |
| Protocol share link | May start with ss://, vmess://, vless://, or trojan:// | Read it from the clipboard or a QR code, then check the protocol fields after importing |
| Server parameter list | Lists details separately, such as Address, Port, password, or UUID | In Add Server, select the correct Type and enter each field |
| Account web page | Prompts you to sign in or displays plan details and instructions | Return to the provider's site and find the actual subscription URL |
The example https://example.com/sub?token=xxxx below is a placeholder address that cannot be used to connect. A token in a real subscription URL acts like an access credential. Don't share it in public screenshots, group chats, or troubleshooting notes; redact the entire authentication parameter before reporting an issue.
Subscribe: Save a subscription and fetch its server list
Subscribe isn't a separate page alongside Add Server; it's a Type option within Add Server. To keep the source available for updates, save the subscription itself rather than splitting its contents into manually added connections. The steps below use only an address obtained from your provider.
-
Open the add screen
Go to Home, tap “+” in the upper-right corner, and open Add Server. Make sure you're adding connection details, not importing a rules configuration in Config.
-
Choose a type
Open Type and select Subscribe. Choose the correct type before entering the address. Don't paste a subscription URL into the server fields for Shadowsocks or another protocol.
-
Paste the URL
Paste the complete subscription URL into the URL field. Check the protocol at the beginning, the token at the end, and make sure there are no extra spaces, line breaks, quotation marks, or non-ASCII punctuation.
-
Save and refresh
Add a recognizable label, save, and return to Home. If the list hasn't loaded, pull down on Home to refresh, then wait for the subscription request to finish before checking the result.
-
Check the list
Make sure the subscription contains selectable servers, then choose one. Seeing a saved subscription entry without any servers doesn't mean the connection details were retrieved successfully.
Updating a subscription fetches the remote list again. Your provider may rename, add, or remove servers, or change their parameters, so don't treat manual edits to an individual connection in a subscription as permanent. If you need a temporary adjustment, note the original value and check it again after the next update. Adding the same URL again won't fix incorrect content returned by the server and may create confusing duplicate groups.
Add Server: Enter a single connection manually
If you have only the server address, port, and authentication details, go to Home → “+” → Add Server. Set Type to match the protocol provided by your service provider. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard use different fields and authentication methods; changing Type alone cannot convert one into another.
- Address and Port: Enter the server's domain name or IP in Address, and the port specified by your provider in Port. If the fields are separate, don't include
https://, a web page path, or:443in Address. - Authentication fields: Enter the password, UUID, key, or other details required by the selected Type. Don't reformat an existing password as a UUID just because another protocol uses UUIDs.
- Transport settings: Check each supplied setting, including TLS, SNI, Host, Path, and other transport options. The server Address, TLS SNI, and transport Host may differ; don't assume they should all use the same value.
- After saving: Return to Home, confirm the entry is present and selected, then run Connectivity Test. A label helps you identify the entry, but changing it doesn't change the connection settings.
Don't guess the portA subscription may be downloaded over HTTPS on port 443, but that doesn't mean the servers in it also use port 443. Set the server's Port to the value supplied by your provider. Don't infer whether TLS is enabled from the port number alone.
A manually added connection usually has no subscription source to update from. If your provider changes the password, port, or transport settings, update the connection yourself. If both a subscription and a parameter list are available, save the subscription to maintain the list over time and use the parameter list to verify individual fields.
QR codes: Check what the code actually contains
Open the QR code scanner at the top of Home. If prompted the first time, allow camera access, then point the camera at the QR code from your provider. A QR code is just another way to represent text: it may contain a protocol share link, a subscription URL, or even an ordinary web page address.
- Make sure the QR code comes from your provider and is fully visible and in focus. Avoid glare and don't crop its edges.
- After scanning, check the detected type and prefilled content. If you see a specific protocol and server fields, verify it as a single connection. If it's a subscription URL, make sure to save it as Subscribe.
- If the QR code is on the same device and the scanner offers a photo library option, select the original image. If not, copy the text from your provider instead of repeatedly trying to photograph the screen.
- Return to Home and check the new entry. A subscription should fetch a server list; a single connection should open to show its Address, Port, and authentication settings.
A successful QR scan only means the image content was read. It doesn't confirm that the content works with Shadowrocket or that the remote connection is available. If scanning opens a login page, return to your provider's site to get the connection details. If the link can't be recognized, ask your provider to confirm the sharing format instead of pasting the entire QR code text into Address.
Clipboard: Copy the complete link, without extra text
The clipboard is useful for transferring text on the same device. Use the copy button on your provider's site, or select and copy one complete link, then switch back to Shadowrocket. If an import prompt appears, check the detected content before confirming. If the system asks whether to allow pasting, grant permission so the text can be read. Whether a prompt appears depends on system permissions and the current clipboard content; no prompt doesn't mean the link is invalid.
- Copying a subscription: Even if no prompt appears, go to Home → “+” → Type → Subscribe and paste the URL into the URL field. This manual method makes it easiest to check that the address is complete.
- Copying a single share link: Keep the protocol prefix, such as
ss://,vmess://,vless://, ortrojan://. Don't copy only the characters that follow it. - Leave out extra text: Don't copy instructions such as “Tap to import,” numbering, code fences, blank lines, or chat messages along with the link. Use your provider's copy button when available.
- Keep the encoding intact: Characters such as
%,+,/, and=may be part of the link's encoding. Don't remove or replace them just to make the link look neater.
Protocol support and share-link parsing are not the same thing. Even if a protocol is available under Type, that doesn't mean every custom string starting with its name can be imported directly. If a share link can't be parsed, use your provider's parameter list to enter and check each field in Add Server. Don't guess missing authentication or transport settings.
Verify after importing: Subscription requests vs. proxy connections
“Subscription update succeeded” and “server connection succeeded” are two different stages. The first retrieves connection details; the second uses them to establish a connection. First confirm that a server appears on Home, select one and run Connectivity Test, then turn on the connection. The first time you connect, follow the system prompt to add a VPN configuration.
Next, check Home → Global Routing. When troubleshooting, first identify the routing mode so you don't mistake a direct connection caused by rules for an unavailable server. This section compares Config, Proxy, and Direct only. Scene is for choosing a scene, so it isn't treated here as a test mode for ruling out rule effects.
Config
RecommendedUses rules from the currently enabled configuration. The route depends on the matching policy and FINAL; a domain that doesn't match a domain rule doesn't necessarily go direct.
Best for: everyday rule-based routing after checking your configuration
Proxy
Routes requests sent through the proxy tunnel via the proxy, helping you temporarily rule out the effects of policies in Config. It can't fix incorrect server authentication details.
Best for: briefly checking the selected server's connection path
Direct
Uses a direct connection. A web page loading in this mode doesn't prove that the selected proxy server is working.
Best for: comparing how your current network connects directly
Bottom line: Find which stage failed
If the list is empty, check subscription retrieval first. If the list is present but the test fails, check the server details. If the test succeeds but requests take the wrong route, check Global Routing and Config. Change one thing at a time and record the results before and after.
A single Connectivity Test result doesn't represent every destination, protocol, or sustained throughput. Keep the specific error message when testing and distinguish timeouts, authentication failures, and parsing failures. Then retest with the same network and server. Don't change DOMAIN-SUFFIX, GEOIP, IP-CIDR, or FINAL to refresh a subscription; these are routing rules, not fixes for a subscription URL.
Import and update issues: Troubleshoot by symptom
“I saved a Subscribe entry, so why is there no server?”
Return to Home, pull down to refresh, and check whether the subscription was actually fetched. Open the subscription and inspect its URL. Make sure it's not a provider login page, redirect page, or incomplete copy. If it returns an HTML page instead of recognizable subscription content, get the correct URL from your provider.
“The update keeps timing out. Should I connect first?”
First check whether your device can reach the subscription domain. If you already have a working server, connect through it and try again. To route subscription requests through the proxy, check Settings → Subscribe → Update via Proxy. If you don't have a working connection, turning on this option won't create one; first troubleshoot your current network or ask your provider whether the subscription is reachable.
“I get a 401 or 403 error. Is the client misconfigured?”
These HTTP status codes mean the server rejected the request. Possible causes include an expired token, account status, or access restrictions. Check the complete URL and confirm your access with your provider. Don't mistake an HTTP error for an incorrect server Port or keep adding the same subscription again.
“I copied the link, but no import prompt appeared. What should I do?”
Make sure you copied a plain-text link and check whether the system blocked pasting. For a subscription URL, go to Home → “+” → Type → Subscribe and paste it manually. For a single share link, check that the protocol prefix and the full link are intact. If it still can't be recognized, use your provider's parameter list to check the details.
“The server is listed, so why won't web pages load?”
Select the target server and run Connectivity Test. Confirm that the connection is enabled, then check whether Global Routing is set as expected. If the connection works but some domains fail, check DNS and the matching rules in Config. Settings → On Demand manages when to connect on demand; it doesn't fix subscription parsing or an incorrect password.
After troubleshooting, remove duplicate entries you no longer need and keep a recognizable label for each subscription. When contacting your provider, include the stage that failed, the error text, the network you're using, and whether Update via Proxy is enabled. Don't share the full subscription URL, password, UUID, or private key.