01 · Subscribe: Create an Updatable Subscription
A subscription saves a remote list as an entry you can update repeatedly; it is more than a one-time way to add a few servers. After importing, check both the subscription entry and the server entries it expands into. The subscription stores the URL and update relationship; the server entries are used to select a connection. A longer list does not prove the subscription is set up correctly, and saving the URL does not prove its contents were read successfully. Distinguish these two layers first to identify whether a problem occurs during updating or connecting.
Before Importing: Identify the Input
Get your subscription from your service provider. Confirm that it is a subscription URL for Shadowrocket, not an account page, an instruction page, or a link for a single server. Subscription URLs are often personal credentials. Even if one looks like an ordinary web address, it may grant direct access to a server list. Don’t post the full URL in public notes, group chats, or screenshots. When checking it yourself, avoid exposing its access parameters through screen recordings or clipboard syncing.
Keep a copy of the original text before importing. Check the beginning, end, and middle for spaces, line breaks, or punctuation added during copying. Watch for a period automatically appended by a messaging app or for instruction text selected along with the copy button. Don’t remove query parameters or replace unfamiliar characters with ones that look more familiar. Letter case, paths, and parameters may be part of how the URL is identified. Changing its display name is entirely different from changing the actual URL.
Select Subscribe in Add Server
Open the add menu from Home, go to Add Server, set Type to Subscribe, and enter the complete URL. Save it with a note that will help you identify it. The layout may vary by device, so follow what the app currently displays. Add one subscription at a time and check that its list appears before moving on. Importing several URLs at once makes it harder to identify the source of a failure and can make duplicate entries look like newly added content from an update.
After saving, return to Home and check that the subscription name, expanded entries, and expected servers match. Don’t assume an informational entry in the list is a connectable server; check its type and details if its name includes a status message. Then test a server whose parameters you have confirmed are complete. Importing and connecting are separate outcomes: importing depends on URL access and content parsing, while connecting also depends on server reachability, authentication, and transport settings.
If It Fails: Check Access, Content, and Results Separately
If no entries appear after saving, first check that the URL is complete, then confirm that your current network can reach the subscription host. Opening a page in a browser does not mean it returns an importable list; it may return a login page, notice, or access error instead. Don’t copy text from such a page into server fields. When contacting your service provider, describe the import method, error message, and point at which it occurred. Before sharing a screenshot, hide any personal access parameters in the URL.
If an existing subscription update fails, keep the old entry for now rather than deleting and recreating it. Check whether the servers are still present, whether the selected entry changed, and whether only one entry is unavailable. If the subscription URL has changed, add and verify the new entry before handling the old one. This preserves a fallback and helps distinguish an invalid URL from a server failure. For the shortest connection walkthrough, return to the Getting Started Guide. Don’t keep changing settings before you have identified the cause.
02 · Add Server: Check Fields for Each Protocol
Manual setup is appropriate when you already have the complete details for an individual server. In Add Server, select the Type first, then enter the address, port, and authentication details. Different protocols don’t share one set of parameters under different names: a password cannot replace a UUID, key, or authentication string required by another protocol. If a field is missing, check the original instructions. Don’t infer its value from a similar label or copy authentication details from another working server.
Check Common Fields First, Then Protocol-Specific Details
Enter the hostname or address itself in the server address field; don’t paste an entire web link there. Enter the port separately as provided. A note helps you identify the entry but is not used for authentication. You can combine details such as purpose, source, and transport, but don’t put a password in the name. The same address with a different port may refer to an entirely different service. Conversely, differently named entries may use identical connection parameters, so check their details when looking for duplicates.
Check authentication fields character by character, especially for spaces, similar-looking characters, or long strings truncated by a messaging app. When entering a password, don’t assume it was copied in full just because the interface displays dots. If in doubt, paste it again from your own original record. Don’t reformat a UUID as if it were an ordinary note. Once the address, port, and authentication are confirmed, check TLS and the transport layer. Changing too many things at once makes it harder to troubleshoot.
| Type | Check These Details | Common Pitfalls |
|---|---|---|
| Shadowsocks | Address, port, password, encryption method | The encryption method must match the server |
| VMess / VLESS | UUID, transport, TLS, and related parameters | Changing Type alone does not convert a protocol |
| Trojan | Password, TLS, server name | The connection address may differ from the TLS server name |
| HTTP / SOCKS5 | Address, port, authentication requirements | Whether authentication is required depends on the server settings |
| WireGuard | Key, address, peer, and routing parameters | A key cannot be replaced with an ordinary password |
| Hysteria2 | Authentication, TLS, and UDP reachability | Local network restrictions may affect the connection |
TLS and Transport: Similar Names Don’t Mean the Same Thing
The connection address locates the server. The TLS server name is used during the handshake and certificate verification, while the Host in HTTP transport may be used for application-layer routing. Some configurations use the same value for all of these, but that doesn’t make them interchangeable in every case. If your service details specify a separate name, path, or transport, enter each in its own field. A path’s leading slash, capitalization, and query string may also matter to the server, so don’t shorten it for readability.
If you see a certificate error, first check the server name, device time, and server certificate status. Don’t treat skipping verification as a routine fix. Certificate verification failures and password errors require different troubleshooting: the former usually involve the handshake identity, while the latter involve authentication details. If the current network cannot reach the server port, changing authentication fields won’t help. Check in order: network, handshake, authentication, and actual requests. This preserves useful information better than repeatedly toggling unrelated settings.
Verify After Saving and Understand What You Can Change
Before saving, confirm that Type matches the original details. After saving, test only this server; don’t also switch Config files or local networks. If the new entry came from a subscription, first consider getting corrected details through a subscription update. Changes made directly to fields generated by a subscription may be overwritten by a later update. If you need a separate test, keep an independent manual entry and label it as temporary so you don’t mistake the test results for the original subscription parameters.
Manual entry cannot fill in unknown parameters or verify that the server accepts the combination. A successful save only means the app accepted the input format. If the connection fails, note the specific stage and error before deciding whether more details are needed. For how UUID, transport, and TLS relate, see VMess and VLESS Parameters Explained. If you only need to identify a protocol name, consult the Glossary instead of changing the entire configuration.
03 · Scan QR Code and Use the Clipboard to Avoid Copying Errors
QR codes and the clipboard are just input methods; they don’t determine whether the content is a subscription, a server, or a configuration. A QR code may contain a link for one server or just an ordinary web address. The same is true of copied text. Identify the source and purpose before importing, then check the resulting entry. A success message doesn’t mean the parameters suit your current network, and it doesn’t replace checking the address, authentication, and transport settings.
Before Scanning: Check What the QR Code Contains
Before scanning, confirm that the QR code comes from your existing server details and matches the accompanying instructions. When using Scan QR Code, grant camera access if prompted by the system. If the camera won’t open, check the permission in system settings, then try again. If the QR code is on another device, adjust brightness and distance so the entire border is visible. Glare, cropped edges, heavy compression, and blurry scaling can prevent recognition; changing server parameters won’t fix an image-scanning problem.
If the QR code is an image on your current device, check whether the app’s current interface offers an option to scan from an image. If not, don’t look for a fixed button that may not exist in your current interface. You can use a text link from the original details and import it from the clipboard, then check each field after saving. Don’t upload a hard-to-scan image to a public QR code reader. It may contain a password, key, or full subscription URL, and sharing the image can expose it just as easily as sharing the text.
Clipboard Import: Keep One Type of Content at a Time
When copying, use the full-copy option in the original details whenever possible to avoid missing the beginning or end during manual selection. Return to Shadowrocket and use the clipboard import option shown in the current interface, following the system prompt to allow access if needed. If the expected prompt doesn’t appear, check that the clipboard still contains the text you just copied. Copying something else after switching apps, using a shared clipboard across devices, or copying an image may replace the original text.
Bulk text is especially prone to including numbering, bullets, and explanatory paragraphs. For your first import, use one confirmed link and check its fields before handling the rest. If a block of text isn’t recognized, check for code fences, quotation marks, or message quote markers before changing any characters in the link itself. Line breaks may be interpreted differently by different formats. If you’re unsure, get a clear, individual link from the original source instead of forcing multiple lines into one address.
Three Checks to Make After Importing
First, check the entry type. If you expected a subscription, make sure an updatable subscription entry is present; if you expected one server, check that the corresponding server appeared. Second, verify key fields: at minimum Type, address, and port, followed by authentication and transport settings. Third, check which list the entry belongs to and make sure it hasn’t been mixed into another subscription or a duplicate test. Matching names don’t guarantee identical imports, and different names don’t necessarily mean different servers.
If repeated scans create multiple entries, keep the one you’ve confirmed works and compare the others before deciding what to remove. Don’t delete all existing entries before verifying the new one. If a scanned entry can’t connect, troubleshoot its fields and network instead of scanning the same QR code again. Scanning, parsing a link, and establishing a connection are three separate stages; repeating the first usually won’t fix a problem at the third.
Manage permissions according to what they’re for. The camera is used to scan QR codes; the clipboard is used to read content you choose to copy. Neither is the same as system authorization for VPN configuration. After importing, you can adjust permissions in system settings if you want to restrict access; confirm them again when you use the relevant feature next time. For the first connection and authorization prompts, see the Getting Started Guide. If an entry is present but won’t connect, follow the troubleshooting steps instead of repeatedly resetting permissions.
05 · Update Strategy: Keep a Way Back Before Making Changes
A subscription update rereads remote content and adjusts the local list accordingly. It doesn’t repair each server or guarantee that the server you’re using will remain. Before updating, note which entry is selected, which subscription it belongs to, and whether a Config depends on its name. Treat an update as a controlled data change: check the results before cleaning up old entries. This makes problems easier to track than repeatedly refreshing during a connection issue.
When to Update Manually
You can update manually when service details have clearly changed, an expected entry is missing, or you need to check whether the subscription can still be read. Before updating, note the subscription name and currently selected entry. Afterward, check for additions, removals, or name changes. If the app offers automatic update settings, use the available options as appropriate; don’t assume one fixed interval is right for everyone. Consider the URL’s usage terms and your own needs when deciding how often to update.
Frequent updates don’t make a connection more stable. If the remote list hasn’t changed, repeated reads usually return the same content. An update may not help if a server’s port is unreachable. First decide whether the issue is related to an outdated list, then update if appropriate. A manually added server isn’t linked to a subscription, so updating a different subscription won’t sync changes to it. If the original details have changed, use the management method for those details rather than updating every list.
Update Failed? Read the Error Before Changing the Route
Updating depends on the network path to the subscription host. Sometimes your local network can reach it directly; sometimes the state of your current connection affects access. If an update fails, note whether the error involves name resolution, a connection timeout, authentication, or unrecognized content, then check the relevant step. Don’t change all routing settings just because the message says “update failed.” When testing a different access path, change one thing at a time and check the result so you know what made a difference.
If the URL is reachable but returns a login prompt, access restriction, or empty content, the problem may not be the app’s parser. Personal access parameters in the subscription URL may have changed, or the server may temporarily be returning an error page. Keep a private copy of the original URL and check its status with your service provider. Don’t save an error page as a Config file or use a similar-looking address from the page to create a server. Changing a server port won’t help if the content type is wrong.
Handle Replacements, Renaming, and Unexpectedly Empty Lists
Keep subscription-generated entries as close to the remote list as possible. Direct changes to their authentication, transport, or notes may be overwritten during an update or leave confusing differences. For long-term experiments, create clearly labeled manual entries separate from the original subscription. This keeps update changes traceable to the remote content and avoids mistaking temporary local edits for parameters supplied by your service provider.
If the list shrinks significantly or contains only informational text after an update, stop before cleaning anything else up. Check whether the original subscription is still present, whether the selected entry disappeared, and whether the results match the service details. Don’t immediately delete the entire subscription just to make the list look normal; doing so also removes the URL and source information. If you need to change URLs, add a new entry, verify its expanded list and connection, then decide what to do with the old entry. Also mark expired credentials in your own backup.
Keep app updates, subscription updates, and Config updates separate. App updates come through the App Store; subscription updates read the server list; Config changes affect rules and related settings. They may happen around the same time, but one doesn’t automatically complete the others. When troubleshooting, note what was updated and what changed before and after. That’s more useful than simply saying, “It stopped working after an update.” See the App Store Download Guide for how to get and update the app.
06 · Organizing Multiple Subscriptions: Track Their Sources Before Renaming
The first goal when managing multiple subscriptions is to know where every server came from, not to make the list as short as possible. Matching names, region labels, or similar latency don’t prove that two entries are duplicates. Two servers in one subscription may also share an address but use different ports, authentication, or transport settings. Before cleaning up, check each subscription’s entries and compare their connection parameters so you don’t remove entries that serve different purposes.
Create a Naming System You Can Keep Using
Use stable internal labels for subscription notes, such as “daily,” “backup,” or “test,” optionally adding a short source name you recognize. Names should help identify the purpose, not contain passwords, full subscription URLs, or personal information. Server names often come from the remote list and may change after an update, so don’t rely on a name alone to remember an important entry. For frequently used servers, also note their subscription and key connection details to make them easier to verify when moving devices.
Don’t repeatedly rename every subscription-generated entry just to make the list look tidy. Updates may overwrite those changes, and renaming may break Config relationships that rely on the names. A more manageable approach is to organize subscriptions first and keep the original server names. Use separate manual entries for temporary tests. Region or route labels in a name are just labels from the provider; they don’t prove the server’s actual location, performance, or current availability.
What to Compare When Checking for Duplicates
Compare Type, address, and port first, then check authentication, TLS name, transport, and related parameters. Entries with identical details may be duplicate imports, but first check whether they belong to different update relationships. If two subscriptions happen to contain the same server, deleting one may also remove information about future changes from that source. Decide which one to keep based on your management needs, not just whether the current list looks repetitive.
When handling duplicate names, don’t delete entries in bulk and try to recreate them from memory. Choose one subscription at a time, note its entry details, and complete the checks before moving on. If you need to track why an entry stopped working, keep a private note before deciding whether to remove it. Identify status messages separately: they may describe account or service status, not a server that simply can’t connect. Don’t assume all actual servers are unavailable based on such a message.
| What You See | Check First | Then Decide |
|---|---|---|
| Exact same name | Subscription, Type, address, and port | Whether these are different servers |
| Parameters appear identical | Authentication, transport, and update relationship | Whether both sources need to be kept |
| Duplicate names after an update | Remote changes and old manual entries | Whether to remove the test copy |
| A test fails for one entry | Test method and network conditions | Whether to keep it temporarily instead of deleting it |
Organizing the List Doesn’t Change Routing
Reordering, renaming, or removing duplicates mainly changes how you manage entries; actual request handling also depends on Global Routing and the active Config. A server at the top of the list won’t necessarily be used for every request. With Config selected, requests matching DIRECT still connect directly according to the rules. With Proxy selected, confirm that the server currently selected is the one you intend to use. After organizing the list, check the selected entry again.
Having multiple subscriptions doesn’t mean the app automatically picks the best server from all entries. Any automatic selection or switching depends on the current configuration and relevant features; you can’t infer it from the number of entries. To get a result you can interpret, first test one clearly selected server before trying more complex selection logic. Repeatedly copying a failed test entry into different subscriptions only creates more duplicates; it doesn’t change the server’s status.
After organizing, run a brief check: subscription URLs are still saved, important servers are identifiable, the correct entry is selected, and independent test entries are clearly labeled. If you’re moving to a new device, also note which Config and update relationships you need. Organizing in small batches is easier to undo than clearing a large list all at once. If a term is unclear, check the Glossary. For first-connection questions, see the troubleshooting section of the Getting Started Guide. Don’t delete entries instead of understanding them.
07 · Connectivity Test: Understanding Latency and Sorting
Latency tests help compare initial server response, but they can’t establish throughput, long-term stability, or whether a particular website will load. Different test methods measure different stages. Some focus on address or port reachability; others include more of the request process. Check the current Connectivity Test settings to see what’s being measured before interpreting the results. A low number doesn’t prove authentication is correct or guarantee that data transfers will complete.
Keep Conditions Consistent and Record the Context
When comparing servers, use the same local network and test method, and test within a similar time window. Switching from Wi-Fi to cellular during a test mixes in a change of access network. Background activity, signal fluctuations, and congestion can affect results, too. Start with a few candidates and compare repeated tests before expanding the list. Don’t treat a momentary result as a permanent ranking, or keep changing unrelated settings just to get a lower number.
Batch tests make several requests at once. If your local network or the remote server has limited capacity, results may be less stable than a single test. If one server works in an individual test but sometimes fails in a batch, reduce the test set and check again. If all entries fail at once, first check that the device is online, the test target suits your environment, and the test method isn’t restricted. Don’t immediately assume every server is down.
Distinguish Timeouts, Authentication Failures, and Request Errors
A timeout means the test didn’t get the expected result within the allotted time; it doesn’t identify the cause. The issue may involve address resolution, port access, a transport handshake, or the test target’s response. If you see a specific authentication error, focus on the password, UUID, or other credentials. If a connection is established but a website fails, check rule matching, the destination domain, DNS, TLS, and other request stages. Don’t keep troubleshooting based only on the latency number.
To verify actual use, open a familiar, permitted webpage and check that it loads fully, that continued requests remain stable, and whether the issue affects only a particular destination. Don’t stop at the system showing Connected; that mainly indicates the local connection mechanism is enabled, not that every remote request succeeds. A cached page alone doesn’t prove the network is working either. Check a new request along with the connection details visible in the app.
Use Sorting to Narrow Your Choices, Not as a Substitute for Testing
After sorting by latency, check which list was sorted and whether the selected entry changed. A change in order doesn’t necessarily change the connection being used, and the top entry isn’t necessarily right for every request. Choose a stable candidate from a small group and test it in practice; keep a backup entry as well. Recording the network conditions at the time is more useful than treating one result as a permanent performance label.
Global Routing also affects how you interpret results. With Config selected, a destination may match DIRECT, so a page loading successfully doesn’t by itself prove the selected server works. To check a proxy connection, confirm which policy the test destination actually follows. Change routing modes only to define the scope of a specific test, then restore your preferred configuration afterward. Otherwise, a temporary setting may unintentionally change how later requests are handled.
Low speed and high latency are related, but they aren’t the same problem. Small requests may respond promptly while sustained transfers are affected by congestion, packet loss, server load, or the local network. Check one server at a time, compare different periods and access networks, then review protocol and transport settings, keeping the previous results at each step. For a more detailed layered approach, see Four Layers of Troubleshooting Slow Shadowrocket Speeds. Repeatedly refreshing subscriptions isn’t a substitute for these checks.
08 · Deletion and Backups: Know What You Can Restore
Before deleting anything, confirm whether it’s an individual server, an entire subscription, or a Config file. Each has a different impact: removing one server may affect only the current list, deleting a subscription may also remove its management relationship, and deleting a Config may affect rule selection. Check the app’s current confirmation prompt for the exact behavior. Don’t delete several layers at once without a backup and verification, or treat clearing the list as a general fix for connection problems.
Keep a Backup Checklist, Not Just a Screenshot
A backup should include at least the subscription URLs, parameters for independent manual servers, the Config currently in use, and notes about important preferences you may need to restore. Screenshots can help identify the interface, but often don’t show complete passwords, keys, or long URLs, so they can’t replace the original details. For subscriptions, keep a usable URL so you can retrieve the list again. For manual servers, preserve complete authentication and transport details; a name and port aren’t enough to restore a connection.
If the app currently offers an export or backup option, check which items it covers before saving the result somewhere private that you control. Don’t assume a file named “backup” contains everything, or that an iCloud or device backup necessarily includes every item you need. A safer approach is to inspect the file or perform a controlled restore test without disrupting your working setup. Confirm that the most important subscription relationships and independent entries can actually be recovered.
Why Deleted Entries May Reappear
Servers generated by a subscription are managed by its remote list. If you delete one server individually, the next update may add it again. That doesn’t necessarily mean deletion failed; the update may have synced the remote content again. If you no longer need a subscription, first make sure its URL is safely stored and that your current connection no longer depends on it, then remove the subscription itself if appropriate. If you just don’t want to use a server for now, selecting a different entry has a different effect from deleting it. You don’t need to delete it just to stop using it.
Before deleting, check whether the active Config depends on particular server names or selection relationships. Removing an entry may not automatically provide an equivalent replacement in your rules. After deleting it, check Global Routing, the active Config, and the selected server, then make a real request to verify the result. If the list suddenly looks wrong, stop and check for a local backup or original subscription before taking further action. Don’t erase the remaining clues during the same troubleshooting session.
Restore to a New Device: Verify a Little at a Time
On a new iPhone or iPad, first restore the app through the App Store, then check any required system permissions. Check the App Store listing for system requirements and purchase eligibility. Restoring the app purchase is separate from restoring subscriptions, servers, and Config files; getting the app back doesn’t mean your connection details are there too. See Restore Your App Store Purchase for the steps. Keep the old device intact while preparing to migrate so you can use it to check fields and fall back if needed.
When restoring your data, import one subscription first and check its expanded list. Then restore independent manual entries, select the required Config, and verify Global Routing. Test a real connection before restoring remaining subscriptions and preferences. This order makes it easier to identify which step introduced a problem. Restoring everything at once while changing the network and rules may be faster, but makes it difficult to tell whether a failure comes from the backup or the new device.
After restoring, check the selected entry, subscription updates, test method, and actual requests before deciding what to do with the old data. If you suspect a subscription URL or credentials were exposed, get updated details from your service provider and update your backup; deleting a local copy won’t invalidate exposed credentials. Keep a brief, private recovery note with the data types and restore order, not sensitive values in a public note. For your next connection, follow the main steps in the Getting Started Guide. Use this page to look up field details and management tasks.