Shadowrocket Server Management: Import, update, and back up existing subscriptions

Import with Subscribe: Understand the URL and its response

How subscription records relate to server entries

A subscription URL is an address that can be requested repeatedly; a server entry is a specific connection profile parsed by the client. One subscription can return multiple entries, but the subscription name, entry name, and currently selected server are separate settings. Keep track of each entry's subscription source, then review its protocol and parameters. Saving a URL does not mean the remote content was retrieved successfully, and seeing a name in the list does not mean the server has passed a real connection test.

Before you begin, check the original details to make sure you have the complete URL used for subscription updates—not an account page, information page, or single-server share link. Preserve everything after the question mark, since query parameters may be required for authentication or content selection. When copying, do not include quotation marks, line breaks, chat prefixes, or trailing punctuation. Do not remove parameters just to make the URL look cleaner. Treat subscription URLs as sensitive credentials and never include them in public screenshots.

Add a Subscribe record from Add Server

Open Add Server from Home, select Type, and choose Subscribe. Fill in the URL and an easy-to-recognize label as prompted by the form. The exact layout may vary by display language, so follow the Subscribe option and field prompts shown in your app. Before saving, check the scheme, hostname, path, and parameters character by character. After saving, check whether the subscription group appears, whether server entries were created, and whether the app reports a request or parsing error. Record each result separately.

For your first import, add just one subscription. Confirm that its response can be parsed and that the entries belong to the expected subscription before adding another. This makes it easier to pinpoint an input problem. Once imported, select the server you plan to use in Home and confirm the selection indicator is on that entry; expanding a subscription group does not select a server. Then follow Getting Started to connect and run Connectivity Test to check whether the imported entry is actually being used by the current connection.

How to check an empty list or a failed request

If no servers appear after saving, first determine whether the app reports an access failure or a parsing error. For an access failure, check whether the current network can make the request, whether the URL is complete, and whether the credentials are still valid. For a parsing error, make sure the remote response contains server details rather than a login page, error message, or empty response. Seeing text in a browser only proves that the browser retrieved something; it does not confirm that the content is valid for Subscribe or replace checking the import result in the client.

Do not keep adding identical records to fix an empty list. Duplicate imports make later updates and deletions harder to track without correcting a bad URL. Keep one subscription record, check the input again, and try one update. If the remote details have changed, use the current URL provided by your existing service. During troubleshooting, note which step failed without sharing the full URL with anyone who does not need it. To describe the issue, report the error category, current network, and whether any entries were created.

If a URL that used to work now fails, keep the existing server list rather than clearing data before you know why. Note the entries visible after the last successful update and the current error, then distinguish between a temporarily unreachable server, a change in the returned content, and a change to the local input. The goal is to restore a reliable update source, not just make a few names temporarily appear in the list.

Fill in Add Server fields: Check the protocol; don't infer it from the name

Select Type before entering connection details

Manual setup is useful when you already have complete server details and need to check each field. Open Add Server from Home, choose the correct protocol Type first, then fill in Address, Port, and the required authentication fields. The selected Type determines which fields are needed. Do not enter everything under one protocol and assume changing the name converts it. A label is for identification, not authentication; a protocol name in the label does not prove which protocol the entry uses.

Address usually takes just the hostname or address, with the numeric value entered separately in Port. Do not put a full web URL, path, and port in Address unless the field explicitly asks for a complete URL. After pasting, check for leading or trailing spaces and digits converted to full-width characters by an input method. The address, port, authentication, and transport parameters should all come from the same set of existing server details. Combining fields from similar-looking entries can cause a connection to fail.

Authentication fields are not interchangeable

For Shadowsocks, Method and Password must match the server settings. A VMess or VLESS UUID is not a label and cannot be replaced with an account password. Check Trojan and Hysteria2 credentials against their respective forms and your existing details. For WireGuard, understand the roles of the local private key and peer public key; do not swap them. This table is a checklist, not a universal server template. The required fields depend on the selected Type.

Passwords and keys are usually case-sensitive; do not let autocorrect change them when pasting. If an authentication field appears empty, confirm that the source details really call for it to be blank instead of guessing based on connection results. If your parameters come from a share link, import it as a separate entry first, then compare the parsed fields with your written details on the edit screen. This preserves the original parsed result and can reveal missing transport options, but make sure the link belongs to the same server.

Check TLS, server name, and transport path separately

When TLS is enabled, the connection address may differ from the server name used for certificate validation. Host and Path in the transport settings also serve different purposes from the TLS server name. Do not copy values between fields just because they all look like domains or strings. Check the transport type, path (including slashes and letter case), and server name against your existing details. Do not disable certificate validation to hide a field mismatch. If you see a certificate error, also check that the device date and time are correct and that the domain in your details is still valid.

After saving, reopen the edit screen to make sure no field was left blank or filled incorrectly. Make one evidence-based change at a time, then test; do not change the protocol, port, credentials, and TLS settings all at once. If you have a complete set of parameters known to work, you can create a separate test entry for comparison. Keep the original and test entries clearly distinguishable, and do not make an unverified copy your default server.

Manual entries usually need to be maintained separately; do not assume a Subscribe update will fix their parameters. For subscription-generated entries, check the source details first, since a refresh may recreate their fields. If you are unsure about an English interface term, consult the interface terminology guide to avoid confusing connection parameters with Global Routing options.

Import from a QR code or clipboard: Check the content before saving

Scan QR Code changes only how you enter the data

A QR code carries text; it is not a server protocol. It may contain a single-server share link, a subscription URL, or just a regular webpage. Before using Scan QR Code, make sure the content comes from your own existing server details. After scanning, check the type and items shown by the client before saving. A successful scan only means the text was read from the image; it does not prove the server works. The content still needs to pass format parsing and connection checks.

Open Scan QR Code from the scan option in the app and follow the system prompt to decide whether to allow camera access. Position the complete QR code within the viewfinder. If you do not want to grant camera access, use an available text import method instead; there is no need to change unrelated system permissions. Glare, cropped corners, low resolution, or screen scaling can interfere with scanning. Get a clear copy of the original QR code rather than repeatedly cropping smaller sections.

Check scan results at three levels

First, check the item type: did the scan open Add Server details or create a Subscribe URL record? Second, check the connection fields: are the address, port, protocol, and authentication complete? Third, check the item's source: does the new entry belong to the expected subscription, or is it a standalone manual entry? If scanning opens a regular webpage, the QR code may contain a web address. Do not try to enter the entire URL as server parameters.

Whether a QR code image saved on the same device can be scanned directly from Photos depends on the options available in the current scan screen. If there is no such option, do not assume a hidden gesture exists. You can use the original text you saved or display the QR code on another device you control and scan it. Avoid placing images containing credentials in shared albums, group chats, or screen recordings. Hiding only the label while leaving the encoded area visible does not protect the data.

Remove unrelated text before importing from the clipboard

When copying, select only the complete share link or subscription URL, not an entire chat message. If the system asks for paste permission, confirm that you initiated the action before allowing the app to read the clipboard. If the app shows an import prompt, check the number and type of parsed items first. If no prompt appears, use an import option actually shown in the interface rather than assuming the format is unsupported. Copy once and check once; this makes issues easier to trace than repeatedly replacing clipboard contents.

Rich text can include bullets, quotation marks, invisible spaces, and manual line breaks. You can check the beginning and end in a private plain-text editor, but do not paste credentials into an online conversion tool. When importing multiple entries, check where each one starts and ends so that two links are not joined into one line or a single encoded string split into two entries. If the app reports a different number of items than expected, check the original text before using the incomplete results to connect.

If scanning and text import produce different results, check whether the two inputs actually contain the same content. The QR code may be from older details while the clipboard holds a newer URL, or the text may contain extra escaping. Keep the original details and compare the item type, address, and port; a matching name alone proves nothing. After confirming the import, replace the clipboard contents with ordinary text and delete any sensitive screenshots you no longer need to reduce the risk of accidentally sharing them.

Shared link formats: Preserve protocols, encoding, and field boundaries

How to manage a single link versus a subscription URL

A single-server share link usually encodes connection details in text and creates one or more server entries when imported. A subscription URL points to remote content that can be requested again for updates. Both can be shared through the clipboard or a QR code, but they are maintained differently. A single link's parameters will not update automatically when a remote subscription changes. Entries from a subscription, however, may be added, replaced, or removed on refresh. Identify the type of source before deciding how to keep the original.

Single-server share text may use protocol prefixes such as ss, vmess, vless, or trojan. Whether Shadowrocket can parse it, and which additional fields it includes, depends on the current app's parsing results. The prefix is only a first clue; it does not replace checking all parameters. Do not force an unfamiliar format to import by changing its prefix. Similar-looking text can use different encoding, and changing a few characters does not convert one protocol to another.

Avoid editing encoded text by hand

Some share formats use Base64 to encode parameters; others use a URI-like structure. Base64 is text encoding, not credential protection: anyone who can see the encoded content may be able to decode it. Formats also differ in how they handle character sets, padding, and parameter positions. Do not shorten a link by deleting trailing characters, or treat plus signs and slashes in a long string as formatting to be cleaned up. Keep the original text and let the client parse it.

In URI-style content, a question mark often begins the query parameters, separators divide them, and a hash may introduce a label. But an authentication value can itself contain characters that require percent-encoding, so do not split and rebuild the link by eye. Distinguish changes caused by copying from characters that were part of the original value: decoding repeatedly can damage reserved characters, while unencoded separators can split an authentication value into multiple fields. If you do not know the format, get a fresh copy of your original share text.

Check parsed fields, not the entry name

A link label usually identifies a server; it does not control how the connection works. Two entries with the same name can have different ports, UUIDs, transport paths, or TLS server names. Different names can also refer to identical parameters. To investigate duplicates, compare the protocol, address, port, and key options on the edit screen. Do not use a full link containing credentials as an ordinary label; it could expose sensitive information in lists, search results, or screenshots.

When using sharing to transfer existing details between devices you control, check what is included in the export. A single-server share usually cannot replace the subscription source record, and sharing a subscription should not be treated as a complete Config backup. Before transferring, decide whether the target device needs a server entry, a subscription update URL, or a rule configuration file, then export and verify each separately. Importing one entry only confirms that its format was recognized; it does not mean other settings were transferred too.

Keep rule configuration syntax unchanged. The following only illustrates the structure of a Shadowrocket rule snippet. It contains no server credentials and cannot provide a connection by itself; check the active configuration and policy references before using it. Rules are matched in order. FINAL handles requests not matched by earlier rules and belongs at the end, not before the specific rules.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

Keep server details separate from rule snippets like this. Pasting rule text into Subscribe or treating a subscription URL as a complete configuration file may be accepted as a string, but each input expects a different kind of content. If you are unsure, check what the original data is for, then use the glossary to distinguish Subscribe, Config, and the related rule keywords. This helps avoid accumulating confusing records through repeated failed imports.

Subscription update settings: Distinguish a successful request from changed content

Follow a complete check after manual updates

Updating a subscription means requesting the saved URL again and processing the response. It does not test whether an existing server is reachable. Before updating, confirm which subscription you are about to refresh and note the currently selected server and group. Afterward, check the app's message, changes to the entries, and whether the default selection is still what you expect. A successful request with no changes may simply mean the remote content is unchanged; a changed list does not mean the new entries have passed a connection test. Check both cases further.

Use the update action shown for the subscription record and wait for the result before continuing. Repeatedly tapping while a request is in progress does not help. Frequent refreshes will not fix an incorrect URL and can make it harder to tell which request produced which result. If an update fails, use the message to distinguish a network error, authentication issue, or parsing problem before deciding what to do next. If the URL needs changing, edit the subscription record itself, not just a generated server entry.

Automatic updates are not an instant guarantee

If the current Settings or subscription edit screen offers automatic update options, read their descriptions and available settings before enabling them. Do not assume the app can make a request at an exact time in every background state. Device connectivity, system scheduling, and app state all affect when an update can run. Before relying on new parameters, check the latest observable update result in the foreground and, if needed, run an update and connection test yourself.

Choose an update frequency that reflects how often the source changes; more frequent is not necessarily better. A stable subscription does not need repeated refreshes after one connection failure. If your existing service confirms that its parameters have changed, update and check the affected fields. Automatic updates and automatic server selection are different: the former refreshes data, while the latter concerns the connection profile in use. A refreshed list does not mean the client has switched to a more suitable entry for you.

Keep local edits separate from remote content

Fields generated by a subscription may be rewritten during a later update. If you edit a label, port, or other parameter locally, consider whether the change could be overwritten. Check the current interface and actual update results to see what is retained. If you need to keep custom parameters, create a separate manual entry when the app allows it and note who maintains it. Do not treat a subscription entry as a permanent local record or rely on unverified overwrite behavior.

If entries are added, removed, or renamed after an update, first check whether the remote source changed, then review the current selection. An old server may have been removed, and a new name may have different parameters. To avoid confusion during a connection, you can update when you are not handling a critical transfer. After the update, check the selection indicator again before testing. Track important entries by their parameters and source, not just their position in the list.

To troubleshoot a failed update, compare using another network you control while keeping the URL and client settings unchanged. If it works on the other network, investigate the request path first; if it still fails, check the URL and response format. Do not blame a subscription update problem on a server's latency, and do not clear the list, change the URL, and switch multiple network settings at the same time. Change one condition at a time so the results are meaningful.

A simple maintenance log is more reliable than memory. Note the item, reason for the action, whether entries changed, and the verification result; there is no need to store full credentials. The next time you see the same message, you can tell whether the problem occurred while accessing the subscription, parsing its content, or connecting to a server. This also helps prevent unnecessary imports and deletions from an otherwise healthy list.

Organize multiple subscriptions: Keep sources and selection criteria clear

Label subscriptions without exposing their URLs

When managing multiple subscriptions, the first question to answer is: which record does this entry come from? Use short, stable, recognizable labels based on personal device use or maintenance scope. Do not put full subscription URLs, account identifiers, or keys in a label. Labels should help identify records, not store parameters. Keep enough identifying information in server names to distinguish entries; renaming everything to the same short label makes comparison difficult.

Before adding a second subscription, make sure the first one has imported successfully and passed a real connection check. Add subscriptions one at a time and check which groups and entries appear. If the app supports collapsing groups, collapse those you are not using to reduce visual clutter. Collapsing only changes how the list is displayed; it does not disable or delete anything or change the active connection. Distinguish expanded groups from selected entries, and use the client's selection indicator to identify the server actually in use.

Compare parameters and source records when checking duplicates

Entries with the same name are not necessarily duplicates, and entries with different names are not necessarily independent. Before deciding, compare Type, Address, Port, key authentication and transport fields, and whether they come from separate subscriptions. Keeping similar entries from different subscriptions preserves their update relationships. Deleting a subscription-generated entry directly may only cause it to return on the next update. Before organizing, decide whether you want to reduce visible duplicates or stop maintaining a source record.

Organizing the list does not change routing

When Global Routing is set to Config, requests are handled according to the active configuration's rules. With Proxy, check the selected proxy server or relevant policy. With Direct, traffic is handled directly. The number of subscriptions in the list does not determine which server a request uses. If the configuration refers to policies by name, check that those references are valid; selecting a server in Home does not mean every request uses it.

Take extra care when renaming entries if the configuration refers to them. After changing a name, check whether rules or policies need their references updated. Bulk renaming just to make the list look consistent can add maintenance work. First determine whether the active Config refers to specific names, then decide what to change. For an unfamiliar configuration, keep a copy of the original and test a small change; this is easier to reverse and troubleshoot than renaming every entry at once.

Use a repeatable maintenance order

A consistent routine can keep day-to-day organization manageable: update one subscription, check what changed, test the entries you plan to use, then handle duplicates or entries that no longer work. Finish one group before moving on so you can identify where each change came from. If an update temporarily fails, do not immediately delete and recreate other healthy records. Keep their verified state and limit troubleshooting to the affected subscription.

When the list is large, narrow it down by source first, then use the search or sort options actually available in the interface. An entry may not appear in search because its name changed, its group is collapsed, or a filter is active; that does not necessarily mean it was deleted. Note the current working entry before switching to a test, then return to the intended selection afterward. The aim is to keep sources, parameters, routing, and selection clear—not simply to shorten the list or make every name look the same.

For an interface term, check the glossary. To set up a connection from scratch, return to Getting Started. The organization tips on this page reduce management confusion; they do not change the permissions, validity period, or availability of your existing service.

Latency tests and sorting: Evaluate responses, handshakes, and requests separately

One test result does not represent every use case

Test results depend first on the method used. A port check, a test involving the protocol, and a real web request do not verify the same things. A response may show that one part of the path is reachable; it does not necessarily verify authentication, TLS, rules, and the full route to the target service. Before comparing results, check the current test settings and description to make sure they use the same method rather than comparing values from tests with different scopes.

Batch testing can help narrow down what to investigate, but it cannot prove that the entry ranked first is always the best. Current network conditions, test target, device load, and timing all affect results. Run a group of tests under the same network conditions, then verify a few entries you plan to use with real requests. Results from before a network change reflect the earlier conditions; do not rely on them without testing again.

Run Connectivity Test for the current connection

Select the server you plan to use in Home and confirm the selection indicator before turning on the connection. If the system asks to add a VPN configuration, review the prompt and confirm only if you intend to proceed. Then run Connectivity Test and check Global Routing as well. If you are using Direct, a successful test does not prove that a proxy server's authentication is correct. With Config, also consider which rule the test target may match and which policy that rule uses.

For a real-world check, test a destination you actually need to reach. If Connectivity Test succeeds but an app still fails, check whether the app's request matches a different rule, whether domain resolution works, and whether the destination service has its own issue. Do not stop checking just because the system shows a VPN status: that indicates the connection configuration is active, not that every destination has completed a request. See the first connection checklist for the full sequence.

Troubleshoot timeouts layer by layer

When a timeout occurs, check the underlying network first, then the server address and port, followed by authentication, transport, and TLS. For domain-related errors, also check name resolution and the server name. An unreachable port and rejected credentials occur at different stages; handle them according to the actual message. If the error does not provide enough detail, compare using another network you control while keeping other parameters unchanged. Avoid changing multiple fields without evidence, or the results will not point to a specific cause.

The device's date and time can also affect certificates and some authentication processes. Check that the date, time zone, and automatic settings are correct; do not leave validation disabled to bypass an error. If only one server fails while other known entries work on the same network, focus on that entry's parameters and remote status. If several unrelated entries fail at once, check what they have in common. For more troubleshooting branches, see Troubleshooting timeouts and connection failures.

Sorting changes the display order, not the selection

Sorting by latency makes entries easier to compare, but it does not guarantee that the current connection will switch automatically. After sorting, select the intended entry, check the selection indicator, and test again. Do not compare blank, untested, and failed results as if they were the same value; check how the interface represents each state. With multiple subscriptions, confirm whether sorting applies to the current group or a larger list so you do not mistake an entry's position for its removal.

Keep enough test notes to be useful, but no more than necessary: record the method, network, and whether a real request succeeded. Remove server credentials, subscription URLs, and personal data before sharing troubleshooting details. Test notes are useful for documenting conditions and results, not for displaying numbers that cannot be reproduced. Comparisons can distinguish network, parameter, and rule changes only when the conditions match.

Delete and back up: Confirm the scope, then verify recovery

Identify the item before deleting it

Deleting a server, a subscription record, or a Config file has different effects. Before proceeding, check which screen you are on, what is selected, and what the confirmation prompt says will be affected. Removing a single server from the list does not change the remote subscription content. Deleting a subscription record does not change your access to an external service. Do not infer the scope from a nearby label alone; confirm whether the action applies to an entry, group, or configuration based on the screen and prompt.

If you plan to delete the currently selected server, first identify and test a replacement. If a configuration policy depends on the name you are about to remove, check whether its reference will still resolve. After deletion, return to Home to check the selection, Global Routing, and active Config. Do not assume the client will select the next entry you expect. Even if the system still shows a connection status, verify a real request again.

Subscription entries may return after an update

A server generated by a subscription may be recreated from the remote content the next time you refresh. This does not necessarily mean deletion failed; the local list may simply have synchronized with its source again. To stop maintaining an entire subscription, remove its subscription record and check the confirmation prompt for the scope of related entries. If you only want to stop using one server temporarily, keeping the selection and group display clear is usually easier to manage than repeatedly deleting and refreshing it.

Before deleting multiple entries, do not rely on their positions in the list; sorting, expanded groups, and updates can all change the order. Check each name and source, and narrow the operation to one group if needed. If you do not know whether an entry is referenced by a rule, keep it until you have checked rather than deleting it and trying to infer the relationship from a failed connection. Deletion is a management action, not the first step in routine troubleshooting. Keeping the previous state available often makes issues easier to isolate.

Back up each type of data you need

A complete recovery may require the original subscription URL, manually entered server parameters, Config files, and app options that need to be set again. Backing up a server share link usually does not preserve the subscription update URL; backing up Config does not prove it contains server credentials. When using an export or backup feature provided by the app, read its description and confirm what it includes. A filename or file size alone does not prove the contents are complete.

Backup files may contain passwords, UUIDs, keys, or subscription credentials. Store them somewhere you control with access protection. Do not share them publicly as ordinary documents or put credential values in filenames for easier identification. Before repairing, handing over, or replacing a device, check whether related information remains in local files, QR code images, or the clipboard. Protecting a backup means both keeping a copy and limiting which accounts and devices can access it.

Verify recovery separately from reinstalling the app

Before replacing a device or reinstalling, make sure you have the information needed to restore it. Re-download the app from the App Store. For details on restoring purchases and purchase availability, see Restore Purchases. System requirements are as listed on the App Store page. Reinstalling the app and restoring server data are separate tasks. Do not assume purchase history restores all local settings, or that the existence of a system backup proves the recovery worked.

After restoring on the target device, check each type of data: confirm the subscription URL is present and can update, manually entered fields are complete, the intended Config is selected, and relevant policy names are valid. Then select an expected server, check Global Routing, run Connectivity Test, and verify a real destination. Only after completing this sequence can you know the backup meets your needs. Being able to open the backup file or see a few names is only an intermediate step.

If you suspect a backup or shared file has been exposed, address the affected credentials through the management options for your existing service and update the client entry. Deleting the local copy alone does not change credentials that have already been exposed. After verifying recovery, remove outdated copies as needed while keeping one usable backup with a confirmed scope and purpose. A routine of “save the source details, change the state, then verify the result” is more reliable than trying to reconstruct information after something goes wrong.