Shadowrocket subscriptions and server management
This page is a reference for users who already have their own subscription or server details. For your first connection, follow the quick-start guide to import, select, and verify your configuration, then return to the relevant section for parameter checks, updates, and maintenance. This page does not replace the first-connection walkthrough.
A one-time client purchase is not a service plan. Shadowrocket is a closed-source commercial app for Apple platforms, available exclusively from the App Store. For purchase verification, device compatibility, and purchase questions, see the App Store guide. Check the App Store listing for system requirements.
- Use your existing subscription or server details
- Check the details before testing the connection
- Back up before editing or deleting
Subscribe and subscription records
Know the difference between a subscription URL and a server address
A subscription URL requests a list of servers; a server address identifies the host used by a specific connection profile. Both may contain a domain name, but they do not belong in the same field. Before you start, identify whether you have a complete subscription URL, a single-server share link, or a set of parameters for manual entry. Choose Subscribe only when you have a subscription URL for a server list. A URL beginning with HTTPS is not necessarily a subscription; ordinary web pages use HTTPS too.
From Home, open Add Server and select Subscribe under Type. Fill in the available fields, such as URL, using your existing subscription details, and give the record a recognizable name. Entry locations can vary between layouts, so confirm them by their English labels. After pasting, check that the beginning, end, and query parameters are intact, especially for spaces or line breaks added by messaging apps. Do not replace the subscription URL with a server domain from its list, or remove parameters that appear unnecessary.
Saving a subscription and retrieving its server list are separate steps
A saved subscription record only means the client accepted the entry; it does not confirm that the remote request succeeded. After saving, use the update action available for that record to retrieve its contents, then return to Home and check for the corresponding servers. If you see a subscription name but no server entries, investigate the update result before turning on the connection. If the list already contains entries, check whether they belong to this subscription rather than assuming previously imported manual entries came from the latest update.
The subscription response must contain server descriptions that the client can recognize. A login page, information page, or error message is not importable, even if the URL opens in a browser. Start with any error shown by the client, then ask the provider of your existing service what the address is for and which formats it supports. Do not paste a subscription URL containing credentials into public lookup tools, or repeatedly share the full link in different places while troubleshooting.
| Record | What it stores | What to check |
|---|---|---|
| Subscribe | List URL and update relationship | URL integrity, response format, and update result |
| Server entry | Connection address, protocol, and authentication details | Whether all fields are present and the connection works |
| Config | Rules and related configuration | Active file and rule actions |
Know where subscriptions end and Config begins
A server list and the rules in Config serve different purposes. The server list specifies where to connect, which protocol to use, and which credentials are required. Config determines whether a request uses PROXY, DIRECT, or REJECT. Importing a subscription does not automatically replace the active rules file; switching Config does not fetch servers again. Check each operation separately to avoid mistaking a difference in rule routing for a problem with an otherwise valid server list.
After importing, note the subscription name, import method, and currently selected server, then test it using the first-connection steps. If the list is empty, check the URL, response, and network reachability first. If the list is complete but the connection fails, continue to the parameter and testing sections. Troubleshoot in stages: retrieve the list, inspect the parameters, establish the connection, then access your destination. Avoid changing the subscription, Config, and DNS at the same time; otherwise, it is difficult to tell which change affected the result.
Add Server manual-entry fields
Type determines which fields you need
Manual entry is useful when you have complete server details and need to check them one by one. From Home, open Add Server, select Type, and then fill in the fields that appear. Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 require different details. Fields that appear or disappear when you change Type are not interchangeable aliases. Use the protocol explicitly stated in the original configuration; trying different types cannot make up for missing parameters.
Address usually takes the server hostname or IP address; Port takes the port supplied by the other end. Unless the field specifically asks for a URL, do not include a protocol prefix, web path, or query string in Address. A domain name and an IP address are not always interchangeable: using a domain may involve DNS resolution, certificate names, and server routing. If your original details specify a domain, enter it as provided rather than substituting the resolved IP to reduce variables.
| Parameter type | Purpose | Common mistake |
|---|---|---|
| Address / Port | Identify the connection endpoint | Pasting a full URL into the host field |
| Password / UUID | Provide authentication for the selected protocol | Including line breaks, omitting characters, or mixing credentials |
| Method | Specify the matching encryption method | Choosing an option based only on a similar name |
| TLS / SNI | Set up the secure connection and server name | Treating the connection address and certificate name as the same field |
| Host / Path | Provide the required transport-layer parameters | Removing a path or changing its capitalization |
Check authentication, transport, and TLS separately
Password, UUID, and similar values are authentication data; preserve every character and its capitalization. The Shadowsocks Method must match the other end—encryption options are not all interchangeable. If VMess or VLESS specifies a transport, check its related fields too; Host and Path at the transport layer may be used to match requests. Correctly entering the address, port, and credentials does not guarantee that all other required parameters are filled in.
TLS, SNI, and the connection address are related, but they are not the same thing. The connection address identifies the endpoint; SNI, when required, provides the server name; certificate verification checks the connection identity. If the original configuration specifies a name, check that exact value. Disabling certificate verification is not a standard fix. For certificate errors, check the device date and time, confirm the names match, and check the remote certificate before reviewing transport settings. Do not just change the port.
Do not reuse protocol-specific fields across protocols
WireGuard uses a different set of relationships between Private Key, peer public key, Address, Allowed IPs, and MTU. Here, Address may refer to the tunnel address, not the ordinary server address; Endpoint identifies the peer. Fill in Hysteria2 authentication and transport options according to the original details as well. For help understanding WireGuard fields, see the WireGuard parameter guide. Do not infer missing values from fields used by another protocol.
Before saving, compare every field with the original details, paying special attention to leading or trailing spaces, full-width punctuation, and automatic line breaks. Reopen the editor after saving to confirm the values were retained as expected, then test the connection. If the error occurs during authentication, check the credentials first; if the endpoint cannot be reached, check the network and address. Change one field per test and record its previous value so you can identify the combination actually provided by the service.
Import using a QR code or clipboard
Scan QR Code reads the encoded content
A QR code is just a way to carry text; its appearance does not tell you whether it contains a subscription, a single server, or an ordinary web address. Before using Scan QR Code, make sure the code comes from your own configuration details and is fully visible, well lit, and in focus. The system may ask for camera access the first time; allow it only if you need the feature. If scanning fails, check image quality and permissions. Do not edit or delete existing servers just to “make room.”
After a successful scan, check what kind of record was imported. A QR code containing a single-server link usually creates one connection entry; a subscription URL still needs to retrieve its list. If a confirmation screen appears, check whether Type, Address, and the name look right. Successful recognition alone does not mean all parameters are present. QR codes can also contain outdated credentials, so test the connection after importing; scanning does not confirm that the remote configuration is still valid.
Keep the full text intact when importing from the clipboard
When importing from the clipboard, copy only the link or configuration text you need. Do not include explanatory text, numbering, code fences, or punctuation at the end of a sentence. If the current screen offers a clipboard import option, follow its prompts. When the system asks for paste permission, check which app initiated the action. Import soon after copying to reduce the chance that another copy action replaces the contents. If the clipboard is empty or has been overwritten, copy the original details again rather than assembling remembered characters by hand.
Long links may wrap visually in chat apps, but a visual wrap is not necessarily a real line break. Conversely, copying multiple lines may include actual line breaks. If the format is not recognized, check the prefix and ending first, then make sure the middle has not been truncated. Do not replace all spaces at once; names and encoded content can handle spaces differently. The safest approach is to copy the entire original text again and compare key fields after import.
Handle duplicates, batch imports, and scan failures
Before importing in bulk, confirm that the current import method supports the text format. Multiple links on separate lines are not necessarily treated as a subscription; some entry points accept only one record. Test the entry point with one valid item you already have, then import the rest. After importing, compare the number and relationships of entries by protocol, address, and port—not just by name. Two records with the same name can point to different endpoints, while differently named records can have identical connection details.
After importing duplicates, do not immediately delete records by name in bulk. First identify which records are managed by subscriptions and which were imported manually, then check which one is in use. If QR and clipboard imports produce different results, compare the original content carefully, especially for an extra link next to the QR code. If the same details fail to import using both methods, the format or content is more likely at fault than the camera; check the structure in the share-link section.
After importing, return to Home, select the new record, and test it again. Existing connections may not have switched to the new server, and a browser may still show a cached page. Record the current selection and use a new request to check the result. If you only need to confirm that the import worked, stop at the parameter check; you do not need to turn on On Demand just to test. Separating import from connection testing makes it easier to pinpoint a failure.
Subscription update strategy and troubleshooting
Updating a subscription changes the list, not every setting
A subscription update requests the URL again and parses its response. It may add servers, remove old entries, or change existing parameters. This is different from updating the app through the App Store or updating a Config file. An app update does not guarantee that subscription content is refreshed, and a successful subscription update does not mean the rules file changed. When troubleshooting, identify which type of update occurred; do not use old server names to judge whether the current configuration is complete after the list changes.
Before updating, note the entry currently in use and any fields you have edited manually. A subscription record may be rebuilt or overwritten when its contents are retrieved again, so do not keep important local changes only in its child entries. If you need to preserve a test configuration, save a separate copy and label its purpose before updating. How the subscription identifies entries and how the client displays changes can depend on the content format; do not assume that the same name always refers to the same underlying record.
When to update manually and what automatic updates do
Manual updates are useful after an initial import, when you receive a configuration-change notice, or when checking again after troubleshooting. If the current settings offer automatic updates, enable them only if needed and confirm which item they apply to. Automatic updates are not continuous monitoring, and background activity may depend on system conditions. Before important use, check the list and the latest visible update result rather than assuming that an enabled setting means the content refreshed on schedule.
Do not repeatedly trigger updates in quick succession after a failure. Repeating the request usually will not fix an incorrect address and may fill the logs with the same error. Keep the error message, confirm that the device's network works, then determine whether the failure involves DNS resolution, a connection, the response status, or content parsing. If the subscription URL has changed, edit the correct record and verify the full details instead of repeatedly adding subscriptions with the same source but different statuses.
| What you see | Check first | Next step |
|---|---|---|
| Cannot connect to the address | Network, DNS resolution, and URL spelling | Restore basic network access, then retry once |
| An error status is returned | Whether the link is valid and credentials are current | Check with the provider of your existing service |
| Content cannot be recognized | Whether the response is a web page and the format is supported | Confirm what the response is intended to contain |
| Update succeeds, but entries change | Whether the returned list has changed | Check the selected entry and its parameters again |
After a successful update, check the record in use
After an update reports success, check that the entries under the subscription look right, especially whether the current selection is still present. If the old record was removed, select a valid entry and test the connection again. If the client still shows previous results, distinguish between a list that remains visible and a successful request this time; a cached list only confirms that local data exists. Conversely, an unchanged list does not necessarily mean the update failed—the remote content may simply be unchanged. Check the update feedback as well.
If basic network access and proxy traffic behave differently, first determine which route the update request actually uses; do not assume it follows the currently selected server. If latency tests are normal but the subscription domain cannot be resolved, see DNS and resolution troubleshooting. Do not change DNS, routing mode, and the subscription URL at the same time without recording their original values; changing several variables makes the cause of a success or failure hard to isolate.
After maintenance, a short note is enough: whether content was retrieved, which entries changed, and whether you tested again. Do not include full subscription credentials. If an update makes the current connection unusable, compare it with a confirmed working backup before checking the new parameters. Do not reimport an old list into the same subscription and expect future updates to preserve it; ongoing maintenance depends on valid subscription content.
Name multiple subscriptions and organize servers
Name records by how they are managed, not by how they perform
If you have multiple subscriptions, give each record a name that distinguishes its purpose, such as personal testing, everyday use, or a backup. Label independent manual records by source category as well. Names should help you find records, not contain credentials, full addresses, or temporary test results. A latency value in a name can quickly become outdated, and a permanent “working” label can mislead later maintenance. Good names describe ownership and purpose rather than promising current performance.
A subscription name and the names of its servers describe different levels of the list. When maintaining records, identify which subscription a server belongs to before checking its connection details; do not judge duplicates by display name alone. Different subscriptions may return records with the same name, and one subscription may return several similarly named entries. Give local test copies a distinct label so you can tell what is remotely managed and what you need to maintain yourself.
Compare key fields to identify duplicates
To check whether records are duplicates, compare at least Type, Address, Port, and relevant transport parameters. For protocols that require authentication, also confirm whether the credentials match, but do not copy them into ordinary notes. Even with the same endpoint, different credentials or transport options may serve different purposes. Conversely, records with different names but identical connection fields may be duplicate imports. Before deleting anything, check the current selection so you do not remove an independent record in use.
Do not copy every subscription entry into a manual record just to make the list look consistent. Doing so breaks the update relationship, leaving you to correct changed parameters one by one. A separate record is appropriate for a test copy that needs fixed parameters; label it clearly to show that it will not follow changes to the original subscription. If the same address was added as multiple subscriptions, check whether they serve different filtering or management needs before consolidating them. Similar-looking URLs alone are not a reason to remove records in bulk.
Keep list organization separate from Global Routing
Sorting servers helps you find and select them; Global Routing determines how requests are handled. A record at the top of the list does not automatically become the route for every request. Check the selected server, the policies in Config, and the routing mode separately. After organizing the list, return to Home to check the current selection, then open the active Config and review its rule actions. Renaming or reordering records alone is usually no reason to rewrite the entire rules file.
| Mode | What it does | What to check after organizing |
|---|---|---|
| Config | Handles requests according to the current configuration | Whether rules and policies refer to the intended records |
| Proxy | Routes requests through a proxy | Current selection and connection status |
| Direct | Routes requests over a direct connection | Do not treat a successful visit as proof that the proxy works |
For a long list, use the grouping, search, or sorting features available in the current interface to narrow the options before checking parameters. Use the actual interface as your guide; there is no need to rebuild every record to match a particular layout. Organize one subscription at a time and confirm its entries are still recognizable before moving on. Working in batches makes it easier to return to the most recent change if something goes wrong, rather than facing a whole page of changed records.
Organization also includes protecting sensitive details. Notes about a record's purpose should not contain Password, UUID, or a full subscription URL. Before sharing a screenshot, check whether subscription names reveal private identifiers. If you want the same organization across devices, establish naming rules and a backup scope on one device first, then restore on the other and compare. Renaming records manually on multiple devices at once can cause confusion; make the maintenance order clear before worrying about names.
Interpret Connectivity Test results and sorting
Start by identifying what the test measures
Interpret Connectivity Test results in the context of the selected test method. Different methods may check endpoint connectivity, access a test destination through a proxy, or test another specific stage. A single number cannot describe the whole experience. Before testing, check the relevant settings, test destination, method, and current network. Do not compare or sort results from different networks, destinations, or methods as if they were measured under the same conditions.
A responsive endpoint does not mean authentication, TLS, transport, and access to the destination all work. A server may show a latency result but fail on an actual request because credentials have expired or parameters do not match. Conversely, a test destination that is temporarily unavailable does not necessarily mean the server is unusable. Treat the result as a clue, then test a normal destination you need to access. When results differ, locate the failing stage instead of immediately deleting every entry that times out.
Compare and sort under consistent conditions
Before sorting, keep the device network and test settings consistent; do not switch from Wi-Fi to cellular during a test. Repeatedly checking a few candidate entries is easier to interpret than drawing a conclusion from one test of the entire list. Sorting reflects the conditions at that time; it does not guarantee future bandwidth, stability, or access to every destination. Do not overinterpret short-term differences as a change in service quality, or use a single lowest value to choose the route for all future requests.
After choosing a record based on testing, confirm that the selection actually changed, then reconnect if needed and make a new request. Browser caches, existing long-lived connections, and other app sessions can delay what you see, so an old page still being visible does not prove the new server works. Verify with a clearly new action and note the current Global Routing mode. If it is set to Direct, successful direct access does not prove the proxy record is working.
| What you see | Possible stage involved | What to check next |
|---|---|---|
| Endpoint test times out | Network, DNS resolution, address, or port | Basic network access and the original endpoint details |
| Latency appears, but requests fail | Authentication, TLS, transport, or DNS | Error message and record of the actual request |
| Some destinations fail | Rule action, resolution, or destination service | Matching rule and the destination's own status |
| No change after switching | Old connection, cache, or selection not applied | Current selection and a new request |
Break the problem into testable steps
Check in this order: basic network, server parameters, connection status, DNS, rules, and destination service. If basic network access fails, restore the device's normal connectivity first. If the parameters look wrong, compare them in Add Server. Investigate DNS only when resolution for a destination domain is the problem. If every candidate behaves the same way, look for a shared factor such as the current network, test destination, or Config instead of editing authentication fields on each server.
Logs and information in Data can help show whether a request was sent and which route it took. Start with entries from around the time of the current action so you do not mistake an old error for a new result. When sharing troubleshooting details, include only the necessary error category and redacted fields—never full credentials. If latency is normal but pages will not load, see DNS troubleshooting and check resolution and request routing separately.
Keep sorting separate from long-term maintenance. You can retest an entry that timed out temporarily; move an entry to the deletion process only after confirming that the remote service removed it or its credentials were revoked. One test should not trigger a large cleanup or an automatic rules change. Once results are stable, note the test conditions and current selection. Retesting when the network changes is more useful than relying indefinitely on an old sort order.
Delete, back up, and restore on a new device
List the items you need to back up
Before backing up, distinguish subscription records, standalone servers, Config files, and related settings. Saving a rules file does not automatically save every subscription URL and credential; saving server share links does not preserve the full rules and device settings. Check what the current export or sync feature explicitly covers, then decide whether other items need separate copies. If you entered parameters manually and can no longer find the original details, make sure you have a recoverable copy before deleting anything.
When using iCloud features, check the account on the current device and the relevant in-app settings, then confirm the actual sync result. Cloud availability, system storage, and network status can all affect the process; an enabled switch alone does not prove that a backup is complete. Sync is not necessarily a historical archive: a deletion may be reflected on other devices during a later sync. To keep the pre-deletion state, save a separate copy and confirm that the current cleanup will not alter it.
Check ownership and impact before deleting
Before deleting a server, check whether it belongs to a subscription and whether it is in use. Removing a subscription entry locally may not stick; it can reappear at the next update. Deleting a local entry does not change the subscription response or permanently remove it from the remote list. Deleting an entire subscription may have a wider impact. Identify its related entries and the current selection before following the confirmation prompt. Do not delete a whole group just to hide one similarly named entry.
Before cleaning up standalone servers, keep copies of any parameters you need and check whether Config refers to related policies or names. Confirm those relationships in the actual configuration instead of relying on a tidy-looking Home list. After deletion, check the current selection and routing path, then select a valid record and test a new request if needed. If you only want to disable a record, a clearly labeled backup is usually easier to undo than permanently clearing it immediately.
Restore and verify on a new device, step by step
When moving to a new device, follow the restore-purchases guide to get Shadowrocket from the App Store, then restore your own data. The app purchase and connection details are separate: restoring the app does not mean your subscriptions, servers, and Config have all returned. Check the App Store listing for system requirements and purchase eligibility. When making the first connection on the new device, follow the system prompts to authorize the VPN configuration; an authorization prompt does not mean the subscription has been verified.
Start the restore with your original details: confirm that the subscription URL and standalone parameters are valid, then restore server records and Config, and finally check related settings such as Global Routing, DNS, and On Demand. Verify each layer before moving on so that importing several similar backups at once does not leave you unsure which one is active. If the old device still works, keep it unchanged as a reference until the new device has passed checks for the list, connection, and destination access.
If entries are missing after restoration, check the backup scope and selected file before assuming the data is corrupt. If all entries are present but the connection fails, continue to the parameter and testing sections. If subscription credentials have changed remotely, an old backup can only restore the old values; update them using your own current details. For more on sync, export, and migration, see configuration backup and device migration. When finished, note which items were restored and securely dispose of any temporary copies you no longer need.