Shadowrocket
Subscription and Server Management

01 / SUBSCRIBE

Subscribe Importing a Subscription

A subscription is a reusable source of server information, not the address of a single server. When you import one, Shadowrocket requests data from that source and parses the supported content into server entries. Updating the same subscription later may add, remove, or replace entries. The key distinction is between the source and its results: the source determines where the next update comes from; the results are the servers you can select in Home. A display name alone does not confirm that the source is correct or the content complete.

Identify the information before importing

Have the complete subscription URL from your own subscription details. Make sure it is not an account page, an information page, or a single-server sharing link. A subscription URL may contain query parameters, which are part of the address. Do not remove anything after the question mark, or paste along explanatory text, punctuation, or line breaks from a message. If your details include both a subscription URL and an account login page, they are not interchangeable.

In Home, open the add option and choose Add Server. Set Type to Subscribe, then enter the complete URL. If the current interface provides a dedicated subscription option, you can use that instead. The key is to enter a subscription URL, not manually enter a server port. Add a recognizable note, such as its purpose and source label, then save and wait for the results. Button locations and available options depend on the current app interface; do not guess a function based on an icon’s position.

Check three things after the first import

First, confirm that the subscription itself was saved: reopen its edit screen and verify that the URL is complete. Next, check whether servers appeared under the subscription, including their names, protocol types, and group membership—not just a success message. Finally, select an entry and test the connection. Saving the subscription, parsing its contents, and connecting to a server are three separate outcomes; none confirms the other two.

If the list is empty after an update, keep the existing entries and note the error and the stage where it occurred. A URL opening in a browser does not mean it returns parseable subscription data; the server could return a login page, an access restriction notice, or an empty response. Likewise, unreadable text in a browser does not prove the content is damaged. Check the app’s parsing result against the format specified in your own subscription details. Do not post the full response in a public forum.

A subscription list is not a rule configuration

Subscribe is for obtaining and maintaining server details. The active configuration in Config controls rules, policies, and related behavior. Importing a subscription does not mean every website will use a new server. Check the current Global Routing selection, the server actually selected, and the policy references in your configuration. For your first connection, follow the Getting Started steps in order. It is easier to identify problems than when changing subscriptions and rules at the same time.

Importing the same URL repeatedly can create duplicate management entries, making future updates, deletions, and troubleshooting confusing. Before adding it again, look for the existing subscription and try updating it. Create a separate copy only when you need an independent test version, and label its purpose clearly. For an empty-list troubleshooting flow, see How to troubleshoot a failed or empty subscription import. Keep the old list until you have diagnosed the issue so you still have a working reference.

02 / ADD SERVER

Add Server Manual Server Fields

Add a server manually when you already have complete connection details for a server or need to check an entry field by field. Choose the correct Type in Add Server, then fill in the fields shown for that protocol. The protocol is not just a label; it determines the authentication method, data encapsulation, and connection parameters. Do not switch between Shadowsocks and Trojan just because both use a password, or try to change one protocol into another by changing the port.

Check the address, port, and authentication separately

A server address is usually a domain name or IP address. Enter only the host portion required by the field; do not include a path from a web address. The port is the one the server listens on, not an arbitrary number. A note helps identify the entry but is not used for authentication. Putting a username in the note or using a display name as the host will not create a valid connection. After entering the details, dismiss the keyboard and compare each field with the original information, paying close attention to leading or trailing spaces and look-alike characters.

Protocol parameters must be matched as a set

The Shadowsocks encryption method and password must both match. Do not verify the password and overlook the encryption method. VMess and VLESS commonly use a UUID for identity; also check the transport specified in your details. Trojan’s password and TLS-related fields serve different purposes. For HTTP and SOCKS5, enter a username and password separately if authentication is required. Do not invent credentials when none are specified. Available fields vary by protocol and app interface; use the fields actually shown.

With TLS enabled, the connection address and server name may differ. SNI supplies the server name during the TLS handshake, while certificate validation checks the names covered by the server’s certificate. Connecting to an IP address does not mean SNI should also be set to that IP. If you see a certificate error, check the name, device time, and original details before changing validation settings. Disabling validation changes what the app trusts and will not fix an incorrect password or transport path.

If your details specify a transport such as WebSocket, check Host and Path along with the transport options. Paths may be case-sensitive and slash-sensitive; an extra space or missing leading slash can cause the handshake to fail. Hysteria2, WireGuard, and other protocols have their own parameters; do not substitute another protocol’s field list. If required details are missing, obtain them from your existing information rather than troubleshooting by turning on every available option.

Keep the original entry for comparison after saving

For an existing server that will not connect, copy or record its current fields first, then change one suspected parameter at a time. If you change the address, port, and TLS settings together, it will be hard to tell which change mattered. Give manually maintained entries distinct notes so they are not confused with same-name entries from a subscription. Subscription entries may be regenerated during an update, so local edits may not persist and should not be treated as a long-term maintenance method.

03 / IMPORT

Scan QR Code and Import from Clipboard

QR codes and the clipboard are just ways to transfer text; they do not change the server information itself. A QR code may contain a single-server sharing link or a subscription URL, while copied text may only be an explanation. Before importing, identify what you have. Then check whether the app parses it as one server or as a subscription that must fetch its contents. Successful scanning only means the text was read; it does not prove that the parameters are complete or the service is usable.

Make QR codes easier to scan

Use Scan QR Code in the app and point it at the QR code in your existing materials. Keep all four corners within the viewfinder. Avoid glare, tilting, and excessive zoom. If the code is displayed on another device, increase its screen brightness if needed and hold it at a steady distance. Long links create denser QR codes, and compressed chat previews may not scan reliably. Use the original, clear image rather than repeatedly scanning a blurry preview.

If camera access was denied, open the system settings, check Shadowrocket’s camera permission, then return to the app and try again. Distinguish permission problems from QR code problems: if the camera view never opens, check permissions first; if it opens but cannot recognize the code, check image quality. If the current app flow offers an option to scan from the photo library, follow the on-screen instructions. Do not assume every scanning screen has the same option.

Copy only the content you want to import

Before copying, make sure you have selected the complete link, including any part that wraps at the edge of the screen. A visual line wrap may not be an actual line break, but manually joining text can introduce extra spaces. In Shadowrocket, use the clipboard import option available in the current interface, or paste the subscription URL into Subscribe’s URL field. If the system asks to allow pasting, allow it only when you initiated the action. If you deny the request, nothing is pasted; that does not mean the protocol is unsupported.

When copying from a note or message, common mistakes include copying a list number before the link, an explanation after it, or the quotation marks around it. Check both ends locally, then copy again. Do not remove percent signs, equals signs, plus signs, or question marks to “clean up” a URL; they may be part of its encoding or parameters. If a platform replaced the original with a shortened summary or truncated preview, copy from the source rather than trying to reconstruct the URL from the preview.

Check the fields, not just the number of imported entries

After parsing an entry, open its edit screen and compare Type, host, port, and authentication fields with the original details. A QR code may contain outdated parameters, and its display name may match a current subscription entry. Seeing one more item in the list is not enough to confirm a correct import. If repeated scans created several entries with the same name, check their source and key fields individually. Keep the verified entry and remove only confirmed duplicates; do not delete entries in bulk before identifying them.

If a QR code contains a subscription URL, a network request is still needed to fetch its contents. If it contains a single-server sharing link, it usually creates a local server entry directly. Troubleshoot a subscription URL as a fetch problem and a single-server link as a parsing or connection problem. If scanning opens a web page instead of showing server details, first confirm what kind of content the QR code contains. Do not enter an arbitrary address from that page as a server address; that turns an import-source problem into a field problem.

Importing and connecting still involve selecting a server, confirming Global Routing, and allowing the system VPN configuration. For a first-time setup, return to the Getting Started guide and complete the steps in order. If scanning and manual entry use the same information but produce different results, compare the fields in both entries to find the parsing difference instead of repeatedly switching networks to mask it.

04 / LINK FORMAT

Sharing Link Formats and Import Boundaries

A single-server sharing link typically contains the protocol, authentication details, server address, and some optional parameters in one text string. It differs from a subscription: the former describes one connection, while the latter points to a set of content that can be updated. Do not identify a link by length alone or simply by whether it contains a network address. A protocol-prefixed single-server link, a URL for fetching a list, and an informational web page are different data types and should use their corresponding import options.

Check the structure before the parameters

Common prefixes include ss://, vmess://, vless://, and trojan://. A prefix identifies the parsing method, but it does not guarantee that the current app recognizes every extension field in that format. Protocols use different payload structures: some contain encoded data, while others use a structure resembling an address with query parameters. Do not parse them all as “username before the colon, password after it,” and never edit encoded sections directly.

Some links use a hash at the end for a note, and their parameters may use percent encoding. Encoding can represent special characters or non-English names; replacing characters manually can change how the link is parsed. A note usually does not affect the connection, while query parameters may control TLS, transport, or the path. If a name displays incorrectly but the connection works, address the display note. If the connection fails, check the protocol fields instead of treating these as the same problem.

Successful parsing does not guarantee identical parameters

A link may include both basic authentication details and additional transport options. Seeing an address and password after import does not mean every option was accepted. Open the entry and compare it with the original details, including any required transport, secure connection, and server name settings. If the link format has multiple variations, use the app’s actual parsing result as your guide. Check unrecognized fields against your existing information; do not put unknown parameters in the note or address field.

When exporting a server entry as a sharing link, consider whether the recipient needs all of its parameters. Sharing one entry generally does not transfer the entire management setup: subscription update relationships, the current Config, rule policies, and some global settings may not be included. To move to another device, use the layered backup approach in the final chapter. Saving one currently working link does not back up every configuration.

Server details and rule text are not interchangeable

The following is a Shadowrocket rule snippet from the Rule section of a .conf configuration. It is not a server sharing link and contains no authentication details. It sends requests to the example domain through PROXY and all other requests through DIRECT. Before editing, confirm what the corresponding policy means in your active configuration. Pasting this text into Add Server will not create a connectable server.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

Before sharing, clarify whether the recipient needs server parameters, a subscription URL, or a rule snippet. When discussing rules publicly, matching conditions and policy names are often enough; there is no need to share server credentials. To troubleshoot a link, you can note its protocol prefix, whether it has parameters, and the error you saw, while hiding the full authentication details. Encoding is not encryption: an unreadable link is not safe to share.

If you only want certain websites to use an existing server, change the rules instead of repeatedly importing the server list. See How to route selected websites through PROXY to understand rule order and how FINAL works. Identify which layer the data belongs to before choosing an action. This helps avoid assuming that an import failed just because behavior did not change.

05 / UPDATE

Subscription Updates and Recovery from Failures

Updating a subscription fetches the server information currently available at its source; it does not fix every connection problem. If the source changes addresses, ports, authentication, or available entries, an update can bring those changes to your device. It usually will not help if the issue is caused by the device’s network, active rules, or system permissions. Start by describing what happened: did fetching fail, did the list change, or did an existing entry fail to connect? The next checks depend on the symptom.

Keep updates easy to track

Before updating, confirm which server is selected and which subscription it belongs to. Note a few key names and make a backup if needed. Update only the subscription you want to check; do not update every group and change rules at the same time. Afterward, check for an error, see whether the list changed, and confirm that the previously selected entry is still there. A missing name may mean the source returned different content, not that the app deleted it by mistake. An unchanged name does not prove its address or credentials stayed the same.

If an update requires a network request, confirm that the device can reach the subscription URL. In some situations, the current connection path can affect the result. If it is safe to do so, compare different network conditions, changing only one at a time. Repeatedly tapping Update is not a useful test: frequent requests may be limited, and new errors can overwrite earlier messages. After the first failure, record the reason before trying again with a specific change in mind.

Troubleshoot fetching, parsing, and use separately

If fetching fails, check that the URL is complete, the network is working, and the source is still valid. If parsing fails, check whether the response is supported subscription data or has changed to a login page or notice. If the update succeeds but a server will not connect, check the updated server fields, selected entry, and routing policy. Record these as separate cases. “Subscription updated successfully” only confirms a result at the fetch and parsing stage; it does not mean every server has passed a real connection test.

If the source has rotated authentication details, the old list may still show familiar names even though connections no longer work. Conversely, old entries may remain usable after an update request fails. Keeping the current list helps identify which layer changed, but do not treat local cached data as a long-term guarantee. If an update looks wrong, stop any further bulk actions and check the source and original details. Do not immediately delete the entire subscription and recreate it with the same unverified URL.

Update frequency and local edits

Set an update schedule based on actual changes—for example, when you receive a change notice for your existing subscription, find an entry no longer works, or prepare to move to another device. If the current interface offers automatic updates, decide whether to enable them based on your network and usage. Automatic updates are not guaranteed to succeed and do not replace checking the results. On a restricted network or when conserving data, remember that background updates still require network access; they are not local refreshes.

Before making local edits to subscription entries, consider that an update may overwrite them. If the app supports independent entries, use one for long-term custom changes and label how it is maintained; keep the original subscription managed by its source. Do not treat the same server details as both automatically and manually maintained. Otherwise, after an update it may be unclear which source of information to trust, and you may end up testing different copies while troubleshooting.

An app update and a subscription update are different things. The App Store manages app updates; subscription updates fetch your existing connection details. Updating the app does not restore a missing subscription, and updating a subscription does not change the app. For purchases, redownloading the app, and system requirements, see Restore a previous purchase. For connection and parsing issues, see Frequently Asked Questions.

06 / ORGANIZATION

Managing Multiple Subscriptions and Matching Policies

When managing several subscriptions, the goal is not to combine their entries into one longer list but to keep their sources traceable. For each subscription, you should be able to answer three questions: which source updates it, which servers belong to it, and who maintains the entry you are using. Without that context, same-name servers may come from different sources. Updating one while assuming the other was updated too can lead to incorrect conclusions when testing, deleting, or backing up.

Name groups first, then exceptions

Give each subscription a short, stable note, such as “Daily A” or “Test B,” using a purpose and a label of your choice. Do not include the full URL or credentials. Clearly mark manually added entries as locally maintained. Use names whose first part is distinguishable on a narrow screen; avoid giving every entry the same long prefix. Protocol and region can help with filtering, but they do not replace source information, since those details may change after an update.

Same name does not always mean duplicate, and different names do not always mean different servers. To confirm a duplicate, compare the protocol, host, port, authentication, and transport parameters; display names alone are not enough. If two subscriptions contain the same connection details, decide whether you need to keep both update sources. Keeping a source does not mean you have to use all its entries, and deleting a local copy does not stop another subscription from returning the same information.

Keep list management separate from routing

The server list answers “Which connection options can I select?” Global Routing answers “How should requests be handled?” In Config mode, you also need to understand the rules and policies in the active configuration. After organizing groups, check whether frequently used policies refer to a specific entry, the current selection, or another object defined by the configuration. A server at the top of the list will not automatically be used by every rule.

The table distinguishes management layers; it does not replace checking the active configuration. In Config mode, a request may match DIRECT and succeed even if the selected server is unavailable. Conversely, changing the selected server in the list does not guarantee that a fixed policy reference changes with it. After organizing entries, verify the route using actual requests and available diagnostics rather than relying only on the connection switch or the selected row.

Make small changes to keep lists manageable

Organize one subscription at a time. First update its note and confirm its source, then handle confirmed duplicates, and finally retest common requests. Preserve a working state after each group; do not update, rename, delete, and change rules all at once. If you are unsure what an entry is for, mark it for review rather than deleting it. If the app offers filters or collapsed groups, use them to reduce clutter instead of deleting information you have not checked just to shorten the list.

Subscription updates may regenerate names and entries, so review policies that depend on name matching. Automatic selection conditions based on region or purpose in a name may select a different server after names change. Before saving a configuration, confirm that each policy still has available members and does not refer to a deleted entry. Rename entries in bulk only when you understand how the configuration references them. If you only want a cleaner list, changing the subscription note usually has less impact.

Having multiple subscriptions does not guarantee a better connection, and it does not mean you should test every entry. Select a few candidates with clear purposes and compare them using the next chapter’s method. Keep other entries in their original groups for later if needed. This preserves update relationships and reduces the effort of identifying entries before each connection. It is easier to maintain and review over time than repeatedly clearing and rebuilding the list.

07 / CONNECTIVITY TEST

Latency Tests and List Sorting

A latency test reports the response for a particular test method at a particular time. It is not the same as website loading speed, sustained transfer performance, or reachability to every destination. Test methods cover different stages of a connection, so make sure you are comparing the same method. A lower one-time result only means the observed wait was shorter for that test. Real-world performance may still differ if requests also need DNS resolution, a TLS handshake, or additional processing by the destination server.

Keep test conditions consistent

Use the same network throughout a test run; do not switch between Wi-Fi and cellular data midway. Make sure the device is not transferring large amounts of data, then run Connectivity Test or the test option available in the current interface on the same set of candidates. If you can choose a method or target, keep those settings the same too. Record the method and network type along with the result. A number by itself is less useful because you cannot tell whether a later change came from the server or the test conditions.

A TCP test typically checks how quickly a port responds; it does not necessarily complete protocol authentication or reach a destination. Other methods that make a real request may cover more stages, but their results still depend on the test target. An open port does not prove the password is correct, and a reachable test target does not mean every website is reachable. Interpret results according to the methods available in the current app. Do not rank results from different methods together and use them to draw conclusions about reliability.

Assess timeouts, variation, and real-world performance separately

A timeout does not necessarily mean a server is permanently unavailable. It may be caused by the current network, resolution, packet loss, test target, or server status. Retest a small number of entries and compare them with one you know works. If all candidates fail at once, check the device network and test settings first. If only one keeps failing, check its address, port, and authentication. Do not delete entries in bulk after one timeout or assume everything is configured correctly after one successful test.

A few tests at intervals under consistent conditions can reveal repeated, significant variation; chasing the lowest single result is less useful. Testing too frequently also creates extra requests, so do not repeat it indefinitely. Then choose a candidate and make real requests to the websites you use. Check whether pages load reliably and the necessary interactions work. Test against your actual needs: opening one lightweight page does not prove every task will work.

Sorting changes only the display order

Sorting by latency can help identify candidates quickly, but the result is usually a snapshot of the test at that moment, not a permanent priority. The top entry may not be selected, and it will not necessarily be used by every policy in the configuration. After sorting, confirm the selected entry and its group. If your configuration uses automatic selection, check its test target and selection logic separately; manual sorting is not a substitute for configuring a policy.

Region names and protocol types provide context, not guarantees. A displayed region may be a label chosen by whoever maintains the entry and does not fully describe the request path. A protocol that works well on one network may behave differently on another. Compare entries on the network you actually use instead of drawing conclusions from their names. For more guidance, see How to evaluate latency, regions, and protocol types. The key is to keep test conditions comparable.

Use diagnostics to confirm the expected policy

If the test works but access to a destination does not, first check which policy the request actually uses under Global Routing. In the example below, requests to the example domain use PROXY, requests to IPs in China use DIRECT, and all other requests use PROXY. Rules are checked in order. This example only illustrates the logic; do not replace your existing configuration with it unless you understand its behavior. Different requests may match different policies, so the same selected server can produce different access results.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

When troubleshooting, record separately whether the test responds, the protocol connects, the rules select the expected policy, and the destination returns a response. This helps identify whether to change a field, select another server, or adjust a rule. Reducing every problem to latency overlooks authentication errors, rule mismatches, and issues at the destination—and can lead you to disrupt a subscription that was working properly.

08 / BACKUP & REMOVE

Deleting, Backing Up and Verifying Recovery

Before deleting anything, identify whether it is a single server, an entire subscription, or a configuration file in Config. Each has a different impact: deleting one server may affect only the local list, deleting a subscription removes its management source, and deleting a configuration may change routing behavior. Also distinguish local deletion in the app from changes to the source. Local deletion does not invalidate the subscription URL or revoke credentials already shared. If information has been exposed, address the original credentials—not just the entries on your device.

Back up each layer, not just screenshots

The first layer is subscription URLs and source notes; the second is the necessary fields for independent manual entries; the third is the active rule configuration and any settings you need to record. If the current app offers an export or backup option, check which layers it includes before saving the files somewhere secure under your control. Different exports may contain only servers or only configuration. A successfully created file does not mean every setting and entry is included.

Screenshots can record selections and what happened, but they are not suitable as the only recovery material. Long URLs may be truncated, and hidden authentication fields are not saved in a screenshot. At the same time, screenshots may expose connection information through QR codes, subscription parameters, or passwords. Keep recoverable original data as your primary backup and control who can access it. Make separate, redacted screenshots for troubleshooting; do not send someone your full backup.

Check references before deleting

Confirm the entry you plan to delete is not the currently selected server and is not referenced by a frequently used policy. A subscription entry may return the next time the subscription updates; if you want to stop maintaining a subscription, remove the source rather than deleting its results one by one. For a manual entry, make sure its original parameters are backed up first. If names look alike, open the edit screen to identify each entry instead of relying on its position in the list.

Before deleting a Config file, confirm which one is active, save anything you need, and prepare a usable replacement configuration. Deleting a server does not remove references to it from rules; deleting a rule configuration does not remove a subscription source. For bulk cleanup, work in this order: back up, verify, delete a few items, and retest the connection. Returning to a known state after each step is easier to control than clearing everything and trying to find the missing information afterward.

Verify each layer after recovery

On a new or reinstalled device, first get the app from the App Store. See Restore a previous purchase for instructions. App purchase records and server data are separate; restoring the app does not automatically restore all connection details. System requirements and purchase availability are as listed on the App Store page. When restoring data, do not assume a system backup contains every entry—check what was actually restored.

Restore one known subscription or manual entry first. Check its fields and test the connection before restoring other groups. After fetching a subscription, check the current list instead of comparing only its item count with an old screenshot. Then restore the rule configuration and confirm Global Routing, the selected server, and policy references. Finally, check settings such as On Demand if you use them. For your first connection, follow the system prompt to authorize the VPN configuration; a restored file cannot replace system permission.

Sources and credentials in an old backup may have expired, so a failed restore does not necessarily mean the file is damaged. Verify whether the import completes, the subscription updates, and the server connects as separate steps. Names in the backup may also differ from the current list, so recheck fixed references. After a successful recovery, save a record of the current state and clearly distinguish the old backup from a newly verified one to avoid using unchecked data next time.

Keep only the copies you need, and periodically remove sensitive materials you have confirmed are no longer in use. Add updated rules and manual entries to your backup, but do not keep piles of hard-to-identify copies for every temporary test. If recovery still fails, note the stage, steps taken, and redacted error details, then see Frequently Asked Questions. To work through the setup in order again, return to the Getting Started guide.