Official Manual / Subscription and Server Management

Shadowrocket Subscription and Server Management Guide

Identify what you are importing before checking fields, managing updates, and saving backups. This page is organized by task; an entry appearing in the list does not mean the connection is working.

If you’re new to Shadowrocket, start with the Getting Started Guide to follow the main workflow for importing, selecting, and connecting. Use this page for issues beyond that workflow, such as field differences, duplicate entries, failed updates, and recovery. If you already know where the problem occurred, jump to the relevant chapter in the table of contents.

1. Subscribe: subscription entry and first import

A subscription brings a set of servers from a remote address into the client and keeps them linked for future updates. A server entry describes a single connection target. Although both can be added, they are not interchangeable. Before importing, check whether you received a subscription URL, a single-server share link, or a complete configuration file. Page titles and file extensions can offer clues, but follow the provider’s instructions to confirm how the content should be used.

First, distinguish subscriptions, servers, and configurations

A subscription manages a set of servers; a server entry stores connection parameters; Config stores rules and other configuration content. Successfully importing a subscription does not replace the rules in Config. Importing a configuration file does not mean you have all the server credentials you need. First note which layer you intend to change, then check only that layer after the operation. This helps prevent missing parameters from being mistaken for a routing problem.

To prepare for an import, get the complete subscription URL from your provider. Do not use a help page, login page, or redirected browser address as the subscription URL. The link may include credentials after a question mark, so copy the entire string. A chat app’s shortened preview does not guarantee the copied link is complete. Check its beginning and end in a secure local note, and make sure no line breaks were added.

Select Subscribe in Add Server

  1. Go to Home and use the add control to open Add Server.
  2. Under Type, select Subscribe. Do not paste a full subscription URL under a regular protocol type.
  3. Enter the complete URL in the URL field, add a recognizable label that contains no credentials, and save.
  4. Wait for the request and parsing to finish, then return to Home and check that the subscription group and its servers appear.

The add button may appear in different places depending on the interface layout. The key checks are that Type is set to Subscribe and the URL is entered in the dedicated subscription field. Before saving, check for extra quotation marks, spaces, or explanatory text. Do not remove parameters after the question mark to “fix” the format, or rewrite the URL to make it look neater.

https://example.com/sub?token=xxxx

The example above only illustrates the structure of a URL with query parameters. In actual use, keep the path, parameter names, and credentials exactly as received. The subscription URL is not the same as the server addresses returned by the subscription: the former retrieves the list, while the latter are connection targets. Check a failed subscription request separately from a failed server connection; one test cannot replace the other.

Verify the first import and handle failures

After importing, check at least three things: whether the group label is correct, whether the list contains the expected entries, and whether the protocol and address of a sample entry look right. The server count can reveal obvious problems, but cannot determine subscription quality or connection status on its own. Choose one entry for a connection test before adjusting rules. Avoid enabling multiple automatic connection options at once, so you can tell which entry is actually in use.

If the list is empty after saving, keep the error message and recheck the original URL. A redirect to a login page, an expired-credentials message, or an unparseable response points to a subscription response problem. If entries appear but fail to connect, that is a separate connection problem. Do not keep adding the same subscription to try to refresh it; that only creates duplicate groups. Follow the subscription update and empty-list checklist to locate the problem, then retry once you know which layer is affected.

If the device already has other subscriptions, note the currently selected server and routing mode before the first import. Adding a new set is not a reason to delete the old one. Move on to organizing subscriptions only after verifying the new set. That way, if the import does not work as expected, you can return to a known state instead of rebuilding all your settings.

2. Add Server: enter fields and verify the protocol

Manual entry is useful when you have complete parameters and need to add only a few servers, or when you want to compare fields with an imported share link. In Add Server, select the correct Type first, then fill in the fields shown for that type. The same field name can mean different things under different protocols. Do not fill in the address and password first and then switch types based on guesswork.

Start by checking the shared fields

Address should contain the server’s domain name or specified address—not a subscription URL or a webpage with a login path. Port is the port the server listens on; enabling TLS does not automatically imply a particular port. Remarks is a local label and is not used for authentication. Before entering values, compare the original parameters with the fields in the interface. Pay close attention to digits and letters that look alike, half-width characters, and spaces added during copying.

Field categoryWhat to checkCommon mistakes
Address / PortConnection target and listening portEntering a subscription URL or webpage path
Password / UUIDAuthentication parameters required by the selected protocolMissing characters, extra spaces, or mismatched fields
TLS / Server NameEncryption settings and certificate name requirementsUsing the connection address as the certificate name
Transport / Host / PathTransport method and additional parametersMissing a path or changing its letter case

The table explains field categories; it does not mean every protocol has the same options. If an option is missing, first check the selected type and transport method rather than filling in a similar-looking field. If your provider has not supplied a parameter, ask whether it is needed. Do not use a generic online example to fill in a configuration that only looks complete.

Enter identity, transport, and TLS settings separately

For Shadowsocks, check the encryption method and password. For VMess, check the UUID and any relevant options explicitly included in the parameters. For VLESS, check the UUID, transport, and security settings. For Trojan, check the password and TLS-related parameters. Similar names do not mean values can be used interchangeably. For a comparison of VMess and VLESS fields, read the manual entry field guide before checking each parameter.

Transport method and protocol type are separate layers. For example, when using WebSocket, Host and Path may both be required. Keep the path’s slashes, letter case, and query string exactly as provided. The TLS Server Name is used for name verification and may differ from Address. The connection target, host in the transport request, and certificate name each serve a different purpose. Do not change them to match just because they all look like domain names.

When you encounter a certificate error, do not treat disabling verification as a routine fix. First check the device’s time, certificate name, and provider requirements, then verify that the parameters have not been altered. If the server’s certificate is misconfigured, changing the client password repeatedly will not help. When troubleshooting, note the stage at which the error occurs; this is more useful than simply writing “it doesn’t work” and helps avoid changing unrelated fields.

Special protocols and post-save checks

Treat WireGuard keys, peer details, addresses, and routing parameters as a set; the setup cannot be reduced to “address plus password.” Hysteria2 also depends on UDP transport conditions, which a single basic connectivity test cannot fully assess. For these protocols, enter the complete parameters according to the instructions you received. Without clear guidance, do not change bandwidth, routing, or transport options in an attempt to improve speed.

After saving, reopen the entry and check that its type, address, port, and transport options still match the original details. Password fields may be masked; do not reveal all sensitive information just to take a screenshot. If you also have an entry imported from a share link, you can use it to compare how fields were mapped, but do not assume the import is automatically correct. Always use the complete server parameters as your reference.

When troubleshooting manual entry, change one field at a time. Note the old value before each change and use the same test afterward. If you change the address, port, and TLS settings together, even a successful connection will not tell you what fixed the problem. Once it works, record the necessary differences in a private note and add the purpose to Remarks. Do not put passwords, UUIDs, or complete keys in Remarks, where they could be exposed in a screenshot of the list.

3. Scan QR Code and import from the clipboard

Scanning a QR code and importing from the clipboard are simply different ways to pass text to the client; neither changes what the text is for. A QR code may contain a single-server share link or a subscription URL. The clipboard may contain a URL, a configuration snippet, or multiple lines. Before importing, decide whether you expect one entry or a set, then choose what to do based on the recognized content. Successful recognition does not mean the right type of content was added.

Check what the QR code contains before scanning

When using Scan QR Code, fit the entire code in the camera view and keep its edges clear. Avoid glare and excessive zoom. When the system asks for camera access, decide whether to allow it for this scan. If you previously denied access, check the relevant system permission settings. Camera access is only for scanning; it does not grant VPN configuration permission or indicate whether a connection will work.

If the QR code is displayed on another device, scan it directly. If it is saved in Photos on the current device, use image recognition only if the scan interface provides that option. If it does not, use the original text supplied by your provider instead of repeatedly photographing the screen or processing it through an unfamiliar conversion page. A QR code may contain credentials, so treat its image as sensitive when saving, sharing, or displaying it.

After scanning, check the result summary first: does it open Add Server or recognize a Subscribe URL? Do the address and Remarks look as expected? Is it asking you to open an unrelated page? If the result is not what you expected, cancel and check the original instructions. Decoding only means the characters in the image were read; it does not mean they are suitable for the current import method.

Check clipboard content before importing

After copying share text, use the clipboard import option provided by the client. If the system asks whether to allow pasting, grant permission for this operation. Copying and pasting successfully are separate steps: another copy action may have replaced the clipboard, or it may contain only a visible title rather than the actual link. If nothing happens when you import, check the clipboard’s current content type before reinstalling the client.

Multiline text is especially prone to boundary issues. A single share link usually needs to remain intact, and a line wrap in the display is not the same as an actual line break. If the copied text includes explanatory paragraphs, list numbers, or quotation marks, extract the clearly identified link. If the content is a configuration that must be imported as a whole, do not remove any sections. The right cleanup depends on the content type; do not apply the same trimming rule to everything.

  1. Check the original instructions to confirm whether the content is a subscription, a single-server share link, or a configuration.
  2. Copy the complete content, without including explanatory text.
  3. Use the matching import option, review the recognized content, and then confirm the save.
  4. Return to the list and check the new entry, making sure you have not added an existing one twice.

Handle recognition failures separately from permission issues

If scanning fails but the original text imports successfully, first check the image clarity and QR code integrity. If the text cannot be recognized either, check the link prefix, truncated characters, and protocol support. Do not keep trying after cropping off a corner of the QR code; its quiet zone and finder patterns are part of the recognition process. Change only one image or text factor at a time so you can identify what made a difference.

If the paste option cannot read content, first check whether you granted system permission and whether another action changed the clipboard after you copied. If the content is recognized but saving fails, check the parameters and response instead of focusing on permissions. Permission controls whether content can be read; parameters determine whether the content can be used. Check these separately.

After importing, you can copy a plain text string to replace the current clipboard and reduce the risk of pasting the sensitive content by mistake. This does not erase all history or copies on other devices. Temporary images, chat attachments, and copies on other devices still need separate handling. If the content has been exposed publicly, clearing the clipboard cannot revoke access. Ask your provider how to handle the credentials, then check whether the old credentials still work.

5. Subscription update strategy and recovery

Updating a subscription requests its original URL again and adjusts the associated server set based on the response. It does not refresh the entire client or update the app in the App Store. First identify what needs updating: the server list, Config content, or the app itself. Each has a different update process and different failure causes.

Keep a record of the current state before updating

Before a manual update, note the subscription label, selected entry, and general structure of the list. If you are using one of its servers, be aware that an update may remove or rename it, so the current selection may no longer refer to the same entry. Keeping a private copy of essential information before an important operation is safer than trying to reconstruct it from memory after a failed update. A list screenshot alone is not a useful backup if it does not show the fields you need.

Update the existing subscription through its update option; you do not need to add the same URL again each time. Afterward, check the error message, changes to the entries, and current selection. Do not rely only on a brief refresh animation. An unchanged list may simply mean the remote content has not changed; that does not prove the request failed. Conversely, a changed number of entries does not mean every parameter is correct.

Troubleshoot the request, response, and parsing separately

First, check whether the request can reach the subscription URL, including the current network, domain resolution, and connection. Next, check whether the response contains the expected content rather than a login prompt, access error, or expired-credentials notice. Only then check parsing: is the content empty, in an unsupported format, or truncated? Troubleshooting by layer helps avoid changing a server password just because an update failed; the password usually is not part of the subscription request itself.

If the update fails only on a particular network, test with another available network if possible and compare the stage at which the error occurs. Do not paste the full subscription URL into a public testing tool; its query parameters may be credentials. A browser displaying the content only proves that the browser received it under those conditions. It does not guarantee the client used the same network conditions or received the same response format.

If the error points to account status or credentials, get current valid details from your provider and confirm whether you need a replacement subscription URL. Do not test by deleting query parameters, shortening the path, or changing letter case. If you must replace the URL, first note the original group and current selection. After the change, check the new list before removing duplicate content. An old URL being invalid and a new URL working are two separate things to verify.

Make automatic updates easy to track

If Settings offers an automatic subscription update option, check its trigger conditions before enabling it, and turn it on only if needed. Background activity depends on the device state and system scheduling; automatic updates are not guaranteed to run at an exact time. After a long period without opening the app, a network change, or background restrictions, check the list or run a manual update instead of assuming it updated on schedule.

There is also no need to make frequent requests just to “stay up to date.” Repeated attempts make it harder to compare states and may trigger remote request limits. Stop the retry loop, save the full error message once, investigate, and then make one trackable retry. After the issue is resolved, test one entry and confirm the update did not change a parameter or selection your setup depends on.

If the list is empty after an update, stop organizing or deleting entries and keep any existing information that may still work. An empty list could mean the remote response really was empty, or there could be a format or authentication problem; a blank screen alone does not tell you which. Follow the five-step checklist, then compare the entries before and after recovery. For more error categories, see the FAQ.

Keep a simple update record: why you ran it, whether it succeeded, whether the list changed, and whether you retested the connection. Do not include credentials or invent a fixed update schedule. The record gives you a point of comparison if something goes wrong next time; it does not assume that every change was caused by a client setting.

6. Organize multiple subscriptions and configurations

Managing multiple subscriptions is not about merging all entries into one long list. Keep their sources distinct, make the current selection clear, and ensure updates and deletions have an identifiable source. Before organizing, distinguish subscription-managed entries from manually added ones. Matching names do not mean entries belong to the same set, and matching addresses alone do not prove two records are identical.

Use labels for purpose, not secrets

Use subscription labels that make sense to you, such as “Daily A” or “Backup test B.” There is no need to include every protocol field, and you should not add passwords, full subscription URLs, or identity parameters. Server display names may be set by remote content and change during an update. Local management notes should focus on which subscription an entry belongs to and what it is used for, not just the name of one entry.

Duplicates usually come from importing the same content more than once, keeping both manual and subscription copies, or having the same connection target in different sets. To identify duplicates, compare at least the protocol, address, port, identity, and transport settings. Two entries may differ only in a path or certificate name, yet that difference can determine whether they connect. Do not delete entries in bulk just because their names match, or alter remote parameters just to tidy up the list.

If you need to keep a manual copy, label its purpose clearly and note that it will not automatically follow changes to the original subscription. Before removing a duplicate subscription, confirm which set has a valid update URL, which set contains the current selection, and whether the other set has unique entries. Delete only after checking these points, then review the list again after the next update to make sure the duplicates are gone rather than merely hidden for now.

Manage server sets separately from Global Routing

Global Routing determines the overall routing mode; it does not manage subscriptions. Adding a subscription does not automatically make it the current connection target or rewrite rules. When troubleshooting, check the routing mode first, then the selected server and configuration, and only then the specific rules. Confusing these layers can make it seem as though changing subscriptions had no effect.

Routing modeDescriptionWhat to check when managing entries
ConfigConfig: traffic is handled according to the current configuration and rulesCheck which configuration is active and what the policies refer to
ProxyProxy: traffic is handled in Proxy modeCheck which active server is selected
DirectDirect: traffic is handled in Direct modeDo not use this mode to test whether a proxy server works

The table describes routing modes; it does not make absolute claims about how every system handles all traffic. Actual behavior also depends on the system and related settings. If access works in Direct mode, that does not prove the server you just imported works. If a target uses DIRECT in Config mode, that visit is not a proxy connection test either. You need to know which policy the traffic actually followed.

Check configuration references and automatic connections

If a configuration refers to servers or policy groups by name, check those references again if an update changes a name. Do not assume a new entry automatically takes over all the uses of the old name. Back up the configuration before editing, then check references, rule order, and fallback policies. Change one thing at a time so you can compare results instead of changing the configuration and the entire subscription at once.

On Demand controls connection behavior under certain system conditions; it is not a subscription updater. If a connection starts automatically while you are organizing or switching entries, check whether this feature is enabled instead of assuming the list failed to save. For a repeatable test, note the automatic connection setting first, then restore your original setting when the test is done so your everyday behavior is unchanged.

A good order for organizing is to label entries, verify where they belong, confirm the current selection, and then delete only what you no longer need. Return to Home after each step to check the result. If one group stops working, this approach limits the problem to that set instead of disrupting all manual entries and configuration references.

Use consistent purpose labels across devices, but do not assume their lists, selections, or configurations are synced. To reproduce the same result on iPhone and iPad, check the subscription, selected entry, and routing mode on each device separately. Check the App Store page for system requirements and device compatibility. For details, see iPad download and first launch.

7. Connectivity Test: latency and sorting

Connectivity Test results describe how a particular method performed under specific conditions at a particular time. They do not prove that every website, protocol, or continuous transfer will work. Before testing, check the test target, method, and current network. Afterward, verify access in a real task. List values can help with initial screening, but they are not a guarantee of long-term reliability or transfer speed.

Know which layer the test measures

A responsive connection target shows that part of the network path may be reachable. Completing a request through a proxy also depends on identity, encryption, transport, and access to the target. Test methods cover different layers, so success with one method does not automatically apply to another. If the test interface lets you choose a method, check which one is active and use the same method to compare the same set of entries. Do not mix results from different conditions in one sort.

A timeout does not mean you need to delete an entry immediately. The target may be temporarily unresponsive, the current network may restrict the transport, name resolution may have failed, or the test request may not reflect actual use. First, test an entry with a known status on the same network as a reference. Then check whether failures are concentrated in a particular protocol. Only after identifying a shared condition should you return to Add Server to check parameters one by one.

Use a repeatable comparison process

  1. Note the current network and Global Routing mode, and make sure the list is not being updated at the same time.
  2. Use the same test method for each entry you want to compare, and do not switch networks during the test.
  3. Retest unusual results to see whether they persist; do not keep only the best result.
  4. Connect using one entry, then check name resolution and access with a real task.

Keep comparisons focused by reducing variables. Do not download a large amount of data and then attribute a change in the test value to the server. Likewise, do not switch between Wi-Fi and cellular data and continue using the same comparison table. Results vary with time, congestion, and the target; recording the test conditions is more useful than saving a single number. Troubleshooting tests should produce interpretable results, not just the lowest displayed value.

For protocols such as Hysteria2 that use UDP, a basic connection response does not cover all transport conditions. Entries using different transports also cannot be ranked based on a single simple test. For background on protocol design and limitations, read Hysteria2 and QUIC basics. Base management decisions on your actual needs and repeat observations, not assumptions based on protocol names.

Sorting changes only the display order

If the interface lets you sort by test results, first check whether sorting applies to the current group or all entries. After sorting, check which entry is selected; do not assume the first item is the active connection. A subscription update may also change list order or display names, so select entries explicitly instead of relying on which one was at the top last time.

A lower value only means that particular test completed faster. It does not mean large files will transfer faster or long connections will be more stable. For a specific task, first confirm that access works, then check for ongoing interruptions. Frequent switching changes both the route and connection state, making the problem harder to isolate. Testing a few candidates one at a time is more reliable than repeatedly sorting the entire list.

Latency looks normal, but websites will not load

First check that the tested entry is actually selected, that Global Routing is set as intended for the test, and that the target is not matched to a different policy in Config. Then distinguish between a name resolution failure, a connection timeout, and a certificate error. Each points to a different cause. Do not skip DNS and rule checks or re-enter all identity parameters just because the list shows a test result.

If only domain names fail, follow the DNS settings and webpages not loading troubleshooting steps. Do not treat access by a temporary address as a permanent fix; certificates, destination routing, and app requests may still depend on the domain name. If all access attempts fail, check the protocol, transport, and network conditions layer by layer. Do not keep switching routing rules without evidence.

When describing an issue to someone else, provide the test method, conditions, stage of the error, and checks already completed. With addresses and credentials hidden, you can still explain the evidence: “the subscription updates, entries pass the test, but a certain type of access fails.” That is more useful for narrowing down the issue than a screenshot showing latency values alone.

8. Deletion, backups, and verifying a reimport

Before deleting anything, identify its level: deleting one server, removing a subscription group, removing a Config, and deleting the app are different operations. Read the confirmation prompt to check what will be deleted and how much it covers. Do not treat “it is easy to add again” as a backup; the remote URL may stop working, and manual changes may not be recoverable from a subscription.

Choose backups based on what you need to restore

To restore only a server set, you generally need a valid subscription URL or complete server parameters. To restore routing behavior, you also need the configuration in use and its references. To restore manual edits, keep the original values, changed values, and reason for each change. A screenshot of the list can help identify names but cannot replace recoverable fields. Decide what state you may need to restore, then save the relevant information rather than just a file that looks complete.

If the client provides an export or share option for the object, check what the export includes before saving it somewhere secure that you control. Exporting servers may not include rules, and exporting a configuration may not include all local settings. For anything not clearly included, record the necessary state separately, such as the current configuration name, Global Routing mode, and whether On Demand is enabled.

Backups may contain full access credentials. Limit who can see them, and do not put them in public notes, shared photo libraries, or public attachments. Treat subscription URLs as secrets too. Use a purpose-based filename or label; do not include passwords. After updating a backup, check its location and access permissions so temporary copies are not left elsewhere unprotected.

Check references and the current selection before deleting

Before deleting a single server, check whether it is managed by a subscription; if it is, a later update may add it back. Before deleting a subscription, check whether it contains the active connection, unique manual changes, or configuration references. Do not assume deletion automatically fixes every linked item. Afterward, check the list and configuration separately.

If you only need to stop using a set temporarily, first decide whether you need to delete it at all. A clear label and valid backup may make it easier to roll back than deleting everything immediately. If you do delete something, handle one object at a time and confirm its scope before continuing. If the result is unexpected, stop the cleanup and use the information you just saved to restore it before more recoverable data is lost.

Reimporting does not mean recovery is complete

  1. Restore the subscription or manual server first, then verify its type, address, and transport fields.
  2. Restore the required Config next, then check policy references and rule order.
  3. Confirm the Global Routing mode and explicitly select a valid entry.
  4. Run a connectivity test and verify access in real use. Restore automatic connection settings last.

This sequence gives each step its own verification result. If you enable automatic connections before importing configurations and subscriptions in bulk, the connection state may change during the process, making errors harder to trace. Keep the original backup during recovery; do not overwrite it just because the first import succeeded. Once everyday tasks work as expected, save the new verified state as a starting point for future recovery.

When switching devices or reinstalling the app, your App Store purchase history helps you find the app again; it does not guarantee that all subscriptions, servers, and rules will be restored. Getting the app and restoring its data are separate tasks. Check the App Store page for purchase and device requirements. Read the restore purchased app guide, then restore your own data from backup instead of assuming it synced.

Handle changed credentials and old copies

If you are reimporting because a link or credential changed, confirm the new details work and check whether the old entry remains in another group. Deleting a local copy does not revoke remote credentials, and invalidating remote credentials does not automatically remove every backup. Handle these separately: confirm access with your provider, then clean up local copies as needed after recovery.

Before finishing, check three things: can you clearly identify the current connection, are the active configuration and routing mode as expected, and does the backup contain everything needed for recovery? Also clear temporary clipboard content and remove QR images and exported copies you no longer need, without deleting the only valid backup by mistake. The goal is not the shortest list, but a clear starting point for the next update, troubleshooting session, or recovery.

After organizing, return to the Getting Started Guide and run through the full workflow once more. If the issue persists, check the FAQ for the relevant stage: importing, updating, or connecting. Record what you have verified and what remains uncertain to avoid repeatedly changing settings that are already known to be correct.