Shadowrocket
Subscriptions and Server Management

Subscribe: How subscriptions and server entries relate

A subscription is a remote address used to retrieve server details; it is not a server itself. Shadowrocket requests that address and displays any recognized items in the response as server entries. So a reachable subscription URL, a populated list, and a working server are three separate checkpoints. Remote content can also change: the names, number of entries, and order you see today may differ after the next update. Before proceeding, make sure you have a subscription URL intended for Shadowrocket—not an information page, account page, or single-server share link.

Add Subscribe from Home

Use the add control on Home to open Add Server. Select Subscribe under Type, then enter the subscription URL and a recognizable name. The wording or placement of controls may change with the app interface; the item you are adding should still be a Subscribe entry. Paste the full URL into the URL field, not the server Address field. Before saving, check the beginning, end, and query parameters. Watch for spaces, line breaks, Chinese punctuation, or explanatory text copied along with the URL.

The name is for local reference only. Use a label that describes its purpose or source, such as “Personal subscription”; don’t put the full URL in the name. A URL with authentication parameters acts like an access credential: anyone who obtains it may be able to retrieve your server details. After entering the information, save it and check the result: Did the expected entries appear? Was an error shown? Are the entries the expected type? The first retrieval can depend on your current network, whether the URL is valid, and how the remote server responds. Saving alone does not mean retrieval succeeded.

Check the entry point, response, and content separately

If the list is empty, first check that the URL in the subscription entry is complete, then distinguish a request failure from a parsing failure. For a request failure, check your local network, DNS resolution, reachability of the remote server, and authentication. A parsing failure may mean the response was a web page, sign-in prompt, error message, or a format incompatible with the import method. Don’t change protocol fields at random just because the list is empty, and don’t start by deleting all existing entries. Keep entries that still work so you have a recoverable state while troubleshooting.

If the URL contains a long query string, compare it character by character with your original details; matching domains alone isn’t enough. Parameters may distinguish accounts, formats, or access permissions, and a single missing character can produce a completely different response. When reporting the issue to your service provider, describe the error, the steps that caused it, and your network environment. Redact the URL, authentication parameters, and server credentials from screenshots. You don’t need to expose the full subscription to show that an import failed.

Subscribe is not Config

Subscribe is primarily for retrieving server entries; Config organizes configuration rules and related settings. Having a server list doesn’t mean you have routing rules suited to your needs, and having a rules file doesn’t mean you have a usable server configured. After a successful import, return to Home to check which server is selected, then review Global Routing. For rule-based traffic handling, use the Config routing mode, but also check the active configuration. The mode name alone doesn’t tell you which route a request will take.

Finally, verify the connection with a specific web request instead of relying on the list alone. See Getting Started for the full process of enabling the connection, selecting a server, and checking the request path. If the subscription was retrieved successfully but access still fails, follow the testing and sorting section to check each layer. This helps avoid mistaking a server connection problem for a Subscribe import issue.

Add Server: Check each field when entering details manually

Use Add Server to enter details for an individual server or keep a small number of independently managed entries outside a subscription. Before entering them, obtain a complete set of parameters—not just an address and port. Authentication, encryption, transport, and TLS requirements vary by protocol; don’t reuse fields simply because their names look similar. Select the correct Type first, then enter each supplied parameter. This is easier to verify than filling in an address and changing the protocol later, which can add fields that are easy to miss.

Core fields and authentication details

Address is the server’s connection target, usually a domain name or IP address. Enter the service’s listening port separately in Port. Don’t append a web path or an entire share link to Address unless the field explicitly calls for a URL. Keep authentication fields such as Password and UUID exactly as provided, including capitalization and hyphens, and watch for trailing spaces. Remarks is a local label and isn’t used for authentication. A format such as “purpose – protocol – tag” can help distinguish similar entries later.

Protocol fields are not interchangeable

Shadowsocks requires matching authentication details and an encryption method. VMess and VLESS usually also require checking the identity and corresponding transport settings. For Trojan, check authentication and TLS requirements. Hysteria2 has its own authentication and connection parameters, while WireGuard uses a separate configuration structure involving keys, addresses, and peers. These names identify protocol types; they don’t mean that two entries using the same protocol have identical extra fields. If details are missing, obtain the original parameters instead of switching options repeatedly in search of a working combination.

The TLS name, HTTP Host, and server Address may be the same or different. Don’t treat them as interchangeable just because they are all domain names. Address identifies the connection target; SNI relates to certificate identity verification; and Host or a path in some transports may identify the server-side endpoint. Keep these fields as provided when the server specifies them. If a connection fails, compare each value instead of weakening certificate checks to hide a naming error. Check parameter errors and certificate issues separately.

Save, then run a basic check

After saving an entry, return to Home to confirm it exists and that its selection indicator is on that entry. If you have several servers with similar names, don’t rely on the label alone; open the details and recheck the end of the address, protocol, and remarks. Test the new entry before making an actual request. Avoid adding many similar entries at once and troubleshooting them all later. Change one field at a time and note why, so you can tell whether a result changed because of authentication, transport, or your local network.

Manual entries are usually maintained by the user; don’t assume a subscription update will correct their parameters. Conversely, an entry generated by a subscription may be rebuilt from remote content during the next update, so local edits may not last. If you need to make an independent adjustment, confirm how saving works, then save a clearly identifiable manual entry and note how it relates to the original subscription. A duplicate name is not a backup: a backup preserves complete parameters and a way to restore them, not just another title in the list.

If one entry keeps failing while other entries work on the same network, check that entry’s protocol and authentication details first. If all entries fail at once, check your network environment, connection status, and the actual request path. Narrowing down the problem is usually more effective than repeatedly adding or deleting servers.

QR Code and Clipboard: Identify the content before importing

Scan QR Code and clipboard import are input methods; neither determines what the content means. A QR code may contain a single-server share link, a subscription URL, or just plain text. Clipboard contents may also include a title, instructions, or multiple addresses. First identify what you have: a subscription that should update over time, or an individual server entry. Then choose the matching import method. Importing a regular web address as a server, or treating a server link as a Subscribe URL, leads to behavior you may not expect.

Scan QR Code: steps to check

Find the scanner on Home and use Scan QR Code. When the app first requests camera access, decide whether to allow it based on the system prompt. Camera access is only for reading QR codes; it does not authorize a network connection. Keep the entire code in view and avoid glare, steep angles, and blur. After it is recognized, check whether the result is a server entry, subscription information, or another prompt. If you’re asked to confirm, verify the protocol, remarks, and address against your own details before saving.

If the QR code is in a photo on the same device, use the option to read from Photos if the current scanner offers one. If not, return to the original details and copy the text instead of repeatedly photographing the screen. If reading fails, first consider image clarity, cropped edges, compression, and content length; don’t assume the server is unavailable. Until the QR code has been converted to parameters, network connectivity isn’t involved. Troubleshoot those as separate steps.

Copy only the complete text you need

When copying, select one complete link if possible, without including an item number, quotation marks, or trailing punctuation. After returning to Shadowrocket, check any clipboard access or import prompt and confirm the source before proceeding; you can also use an import control shown in the current interface. If the system asks whether to allow pasting, decide based on what you’re doing. No prompt doesn’t necessarily mean the app has a problem: the clipboard content may be incomplete, unrecognized, or affected by the current system permissions and import method.

If no entry appears after import, first check whether the same item is already present, then check whether the text contains only instructions. Don’t copy different content repeatedly just to trigger a prompt; doing so can overwrite the original details. If the text contains several share links, keep an original copy, then import and check them in batches. A successful batch import doesn’t guarantee every entry has correct parameters. Spot-check the protocol type, name, and group; verify important entries individually.

Permissions, saving, and connecting are separate steps

Camera, Photos, and clipboard permissions serve different purposes from the system authorization required to create a VPN configuration for the first time. Importing adds parameters to the device; enabling a connection may prompt the system to allow a VPN configuration. Neither the system status bar nor the Home switch alone confirms that an item was imported. After saving, check where the entry appears, select a server, review Global Routing, and then make an actual request. This makes it easier to identify which stage caused an error.

After a successful import, clear any sensitive content still on the clipboard and manage QR code images according to your own data practices. If you need to keep recovery details, store them somewhere protected—not in a public photo library, shared note, or group chat. Deleting a clipboard copy won’t revoke credentials that have already been exposed. If you suspect a leak, change the credentials through the relevant service’s management interface, then update the client entry.

If the same details produce different results through different input methods, compare the text that was actually recognized rather than the appearance of the QR code. Line breaks, encoding, and missing characters may come from copying or recognition. Break the problem into three checkpoints: “Can the text be read?”, “Can the entry be parsed?”, and “Can a connection be established?” Check each one separately.

Share links: distinguish protocols, encoding, and configuration

A server share link carries parameters. It usually begins with a protocol identifier and includes authentication, connection address, port, and additional settings. A Subscribe URL points to remote content. Both may look like links, but they serve different purposes. Identify the format from its overall structure, not just a protocol abbreviation in its name. An HTTPS address may be a subscription endpoint or an ordinary web page; a protocol link may represent one server and won’t gain update capability just because it’s labeled “subscription.”

A prefix helps identify a format, but doesn’t prove it works

Common protocol share-link prefixes include ss://, vmess://, vless://, and trojan://. A prefix indicates how a link may be parsed; it doesn’t prove that the remaining fields are complete or that the client accepts every extension parameter. Some formats encode content in the link, while others use query parameters for transport and TLS. Import the supplied details as-is when possible, then check the parsed result. Avoid assembling a production entry from memory.

A long encoded string is not secure encryption. It may simply convert authentication and configuration details into text that’s easier to transmit; anyone with the link may still be able to recover them. A trailing label is usually for display; changing it doesn’t change authentication. Query string characters also have a syntactic role: deleting or incorrectly escaping a separator can make the app read different fields. Don’t use text replacement to “clean up” an entire link, and don’t delete unfamiliar parameters as if they were unnecessary.

The difference between rules files and server links

Shadowrocket configuration files are organized into sections. The snippet below demonstrates real rule syntax only; it contains no server authentication details and is not a complete personal configuration. Rules are matched from top to bottom, with FINAL at the end to handle requests that didn’t match earlier rules. PROXY and DIRECT show how a rule handles traffic; they cannot replace a Password or subscription URL. After importing a server, check the active configuration. Don’t paste rule text into the address field in Add Server.

[General]
bypass-system = true

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

In Config mode, the active configuration rules determine how requests are handled. Proxy and Direct modes handle traffic differently. Before testing a server, check Global Routing so a request that actually goes through Direct isn’t mistaken for proof that the selected server works. See How to choose Global Routing for details on the three modes. Understanding this distinction helps separate “the entry parsed correctly” from “the request followed the expected route.”

Keep the original if the format doesn’t match

If content isn’t recognized, fields are missing, or imported parameters look wrong, check the applicable format against your original details. Don’t upload links containing authentication information to unknown conversion sites, and don’t remove TLS, paths, or other transport parameters just to clear an error. You can check for curly quotes, line breaks, and truncation locally, but make parameter changes only when you have a clear reason. Different field combinations may reflect different server settings; saving successfully doesn’t prove they can establish a connection.

When describing a format issue to your service provider, include the protocol type, import method, stage where the error occurred, and missing fields. Don’t share the full link. Keep an original copy for comparison, but treat it as a credential. If you confirm that the client can’t currently interpret part of the details, obtain the applicable parameter instructions before deciding whether to enter them manually or import them again. Don’t guess the connection method from incomplete text.

Subscription updates: check the result before changing strategy

A subscription update requests a remote address again and processes its response; it does not update the app. App updates come through the App Store. Server list updates depend on the Subscribe entry and its remote content. These updates affect different things and have different failure and recovery paths. An update may change names, add entries, adjust parameters, or remove old entries. Before updating, note which server you’re using and which subscription it belongs to so you can accurately check what changed afterward.

Use a manual update to establish a baseline

When setting up a subscription for the first time, perform one manual update and check the result. Update the relevant subscription entry or use its related action menu on Home, then review its server list. The exact control depends on the current app interface; don’t mistake a single server’s test for a subscription update. A successful baseline means there’s no clear request error, the list parses, and important fields match what you expect. The update finishing doesn’t mean every server can connect.

If the interface shows an update status or time, use it as a clue, but don’t rely on it alone to decide whether remote content changed. Compare one or two known entries and check that their names, protocols, or addresses match your current details. A remote list can be returned successfully even when its contents haven’t changed; conversely, a web error response isn’t a valid server list. If something goes wrong, keep the error message and context. Avoid tapping update repeatedly, which can obscure the first failure.

Plan automatic updates around recovery

If the current Subscribe settings offer automatic updates or an interval, choose one that suits your usage and network conditions, and first confirm that manual updates work reliably. Automation can’t fix an invalid address, incorrect credentials, or an incompatible format; it only repeats the request under the configured conditions. An interval is not a guarantee of exact background execution. Device state, system scheduling, and app conditions can affect when an update actually occurs. Before important use, check the result yourself instead of assuming remote changes have synced.

A mobile network and Wi-Fi may not have the same reachability. When an update fails, note the network, connection switch state, and error type. Don’t assume the update request necessarily goes through the currently selected server; the actual path depends on app settings and network conditions, so check the observable result. If switching networks makes it work, investigate name resolution or access on the original network instead of immediately rebuilding every subscription. Change one condition at a time to keep the cause clear.

Name changes after updates and local edits

A remote subscription is usually the source of parameters for the entries it generates, so later content may overwrite local changes to names or fields. If you need a separate entry for a special purpose, manage it independently and note that it won’t automatically inherit remote changes. A server removed remotely may also disappear from the local list; that’s different from deleting it manually. If the previously selected entry is gone after an update, check what’s now selected. An enabled Home switch doesn’t mean the same server is still in use.

A failed subscription address and a failed server connection are separate problems. If the subscription request fails but a saved server still connects, the issue may be the list source. If the list updates successfully but all servers fail, check authentication, server-side changes, and your local network. If the remote service has changed the subscription address, edit the correct Subscribe entry and verify the new result. Remove the old entry only after confirming the new one is stable; matching names don’t prove two entries are equivalent.

If a web page fails after an update but latency still shows a value, follow DNS resolution troubleshooting. Track “list retrieval,” “connection established,” “DNS resolution,” and “web request” separately to avoid repeating updates at the wrong layer. Automatic updates should make management stable and verifiable, not simply refresh more often.

Organizing multiple subscriptions: preserve source and purpose

When managing several subscriptions you already have, make sure you know which one generated each server, whether it updates automatically, and why you’re currently using it. As the list grows, similar names, duplicate imports, and local edits can blur where entries came from. The goal is not simply a shorter list; it’s to make updates, tests, and recovery traceable. Before organizing, preserve your original details and identify the entries in use. Don’t delete similar names in bulk when you can’t tell where they came from.

Use names to describe purpose, not store credentials

Give each subscription a stable, recognizable purpose label, such as “Personal” or “Temporary test.” Add a “Manual” marker to independently entered servers. Server remarks can include the protocol or your own usage notes, but not full authentication details or a latency value that will soon be outdated. Latency varies with time, network, and test method. A name should identify an entry, not report its current performance. Consistent labels are enough; a complex numbering scheme isn’t necessary.

If remote subscription names change frequently, a local name edit may be overwritten during an update. Check how edits are saved before relying on them. A safer approach is to keep a brief management note with the subscription’s purpose, how to identify important entries, and what maintenance they need. It doesn’t need to include passwords; it should help you locate the original protected details. Don’t use a screenshot containing a sensitive URL as your only source record: it’s hard to restore from and easy to expose when sharing troubleshooting information.

Distinguish duplicate imports from legitimately similar entries

Entries with the same name aren’t necessarily the same server, and the same address doesn’t necessarily mean the same service. Ports, protocols, authentication, TLS, and transport paths may differ. Conversely, importing the same share link by QR code and clipboard may create duplicates that are hard to recognize. Compare the protocol and connection parameters, then check the subscription source; don’t rely on the displayed name alone. If you’re unsure, mark the entry for review and wait until after testing and backing up before deleting it. That’s easier to undo than an immediate merge.

Several entries pointing to the same address may still suit different network conditions. Verify them against your actual needs instead of guessing from a region name or label. A geographic label doesn’t prove the actual request exit point or a fixed route, and this guide doesn’t evaluate servers on that basis. Decide what to keep based on your own requirements, complete parameters, and test results. Separating verifiable facts from labels can prevent you from rebuilding a local list just because remote names changed.

Organizing entries doesn’t change routing

Moving entries in the list, editing remarks, or changing display order are generally management actions; they don’t prove that routing rules changed. Actual requests still depend on the selected server, Global Routing, and Config. If a configuration refers to a specific name or policy, check whether those references depend on the original name before renaming it. Manage servers and maintain configuration in separate steps: identify the entries first, then check rule references. Avoid changing names, rules, and connection parameters all at once.

You can keep one verified representative entry for each subscription to make a quick check after updates, but it’s only a sample and doesn’t prove the entire list works. You don’t need to enable automatic updates for every subscription. Clarify their purposes first, then decide how often to maintain them. Clean up temporary tests promptly so that months later you can still tell which entries are in regular use and which were created for troubleshooting.

After cleaning up the list, make an actual request to confirm the current selection is still what you expect, then update your management notes. If an interface term is unclear, see the guide to the Home, Config, Data, and Settings screens. Matching each action to a clearly identified entry is more reliable than relying on memory to manage a long list of similar servers.

Latency testing and sorting: understand what the numbers mean

Connectivity Test checks responsiveness under specific test conditions; it does not prove overall availability. Different methods may focus on establishing a connection or receiving a particular response, and results depend on the test address, timeout, and network state. A lower number doesn’t mean faster downloads or that every website will load. To compare servers, use the same method and environment. Results from different times or networks aren’t suitable for direct ranking.

Test a few entries, then verify with a real request

On Home, test a small number of entries you actually need. Check whether the result is normal, timed out, or shows a specific error. After testing, select one entry, check Global Routing and the active Config, then open a web page whose purpose you know. A real check should cover DNS resolution, connection establishment, and page content loading—not just confirm that a title appeared. If you test the list without confirming the selected entry, you may test one server and use another.

Batch testing can quickly reveal obvious problems, but sending many requests at once adds a temporary load to your network and remote servers, and results may affect one another. For a large list, test by subscription or purpose in batches, waiting for results to settle before continuing. Don’t treat a single batch timeout as proof that every server has permanently failed. Retest a known entry individually, then compare under another network condition. Control variables rather than switching servers, changing DNS and rules, and reimporting all at once.

Sorting changes the display, not the selection

If the current interface lets you sort by test results, use it to review those results, but check the selected indicator afterward. A change in display order doesn’t mean the first entry has been selected automatically unless the settings and interface state clearly show that. Test results also become outdated. After moving from Wi-Fi to mobile data, the old order may no longer reflect current conditions. Choose based on current tests, actual requests, and your needs—not on a one-time sort result.

Names, latency, and stability describe different things. Names are supplied by the source or set by the user; latency is the observation from one test; stability takes multiple sessions of actual use to assess. Don’t record an occasional lowest result as a permanent benchmark in the remarks. If an entry works intermittently, noting whether the failure occurred at connection, web resolution, or during transfer is more useful than simply writing “slow.” It also helps distinguish server load, network fluctuations, and configuration differences.

Troubleshoot by failure stage

If subscription updates work but tests generally fail, check server selection, authentication, and network reachability first. If tests return results but web pages won’t load, check DNS, routing rules, and the app’s actual request path. If pages load but large downloads are slow, then investigate sustained transfers under different network conditions. A test result only tells you what happened under its specific conditions; it doesn’t rule out problems at other layers. Tracking each layer prevents every symptom from being attributed to a server failure.

During troubleshooting, you can temporarily select a specific Global Routing mode to distinguish request paths. When finished, restore your usual configuration and confirm how requests behave afterward. Don’t leave temporary test settings in place as a long-term configuration. See Feature Guide for an explanation of the modes, and Troubleshooting for common issues.

For speed comparisons, use the same destination, roughly the same time, and the same local network. Avoid running other high-volume transfers at the same time. If results still vary significantly, note the range and conditions rather than looking for one fixed number. See A layered approach to troubleshooting slow speeds for more checks. Testing helps narrow down a problem; it doesn’t permanently label a server as working or failed.

Deletion and backup: distinguish local cleanup from credential revocation

Before deleting anything, identify the item: an individual server entry, a subscription-generated entry, an entire Subscribe record, or the active Config. Each has different recovery requirements, and an accidental deletion can’t always be undone by updating again. Removing a local entry doesn’t revoke remote access credentials. If you’re responding to a leak, change or revoke credentials through the relevant service’s management interface. Treat “remove from device” and “invalidate old credentials” as separate actions so you can confirm the cleanup is complete.

First identify who maintains the data

For an independent manual entry, recovery usually depends on the original parameters or a valid export you saved earlier; a name alone can’t restore authentication and transport settings. Whether a deleted subscription-generated entry returns depends on subsequent updates and how the list is processed. If the remote list still contains it, the entry may reappear. To make a lasting change to the remote list, address the relevant subscription management relationship instead of repeatedly deleting the same local server.

Before deleting an entire Subscribe entry, make sure you no longer need its server entries and preserve your original URL. Don’t assume related local data will always be kept or removed in a particular way; read the current confirmation prompt, then return to Home and check the actual result. If you’re using one of its servers, switch to a known working alternative and verify an actual request before deleting the subscription. That way, an unexpected result won’t leave you without both a connection and a way to recover.

A useful backup preserves fields and relationships

A backup should include at least your original subscription details, independent server parameters, any Config you need to keep, and the relationship between each item and its purpose. If the current interface offers sharing, exporting, or backup features, use them according to what they actually support; don’t assume a feature includes all data based on its name. After exporting, check that the file or text contains the items you need, especially the difference between a single share link and a complete backup. A Config file shouldn’t automatically be treated as a backup of all server credentials.

Store backups somewhere with appropriate access protection, not in a publicly shared folder, group chat, or unprotected note. A backup may contain subscription URLs, Passwords, UUIDs, or keys; handle it as a credential. A redacted copy for explaining a problem can omit sensitive fields, but it can’t replace recovery data. Store the two separately and label their purpose clearly. Otherwise, when changing devices, you may mistake a text file with critical parameters removed for a complete backup.

When changing devices or reinstalling, restore the app first, then your data

After changing devices, use your App Store purchase history to confirm and get Shadowrocket, then restore your own subscription and server details. App purchase history and in-app configuration data are separate; getting the app again doesn’t automatically restore every entry. Refer to the App Store listing for purchase eligibility, device compatibility, and system requirements. For steps to get the app, see Restoring a previous purchase. After restoring your details, check server selection, the active configuration, and system connection authorization again.

To verify a restore, import a small set of representative details first, check the parameters, and test a real connection before restoring the rest. Don’t delete entries from your old device until you know the backup is readable. Successfully retrieving a subscription doesn’t mean local remarks, independent entries, and configuration changes have all returned. Check each item against a recovery list you prepared in advance. A backup is useful only if the original details are available, the format is readable, the fields are complete, and the result has been verified.

After cleanup, check that the current connection, default selection, and Config match your expectations before handling outdated backups. Keep a recoverable older copy until the new backup has been verified. Once old credentials are invalid or no longer needed, remove them according to your security practices. A record of what you deleted, kept, and how to restore it is more useful than just noting the cleanup date—and helps you find the right details during a future device change or troubleshooting session.

This page breaks down server management by task. To set up a connection from scratch, return to Getting Started. If you can’t categorize an issue, save a redacted error message and the steps that caused it, then check Troubleshooting. Don’t use bulk deletion as a substitute for finding the cause.