Shadowrocket Subscription Guide

01 · Subscribe: Create a subscription you can maintain

First, determine whether you have a subscription URL or server details

Before you begin, identify what your existing information is for. A subscription URL is a remote endpoint used to retrieve a set of server entries, usually via HTTPS. An individual share link describes one server’s protocol and parameters. Both can be long strings, so length alone is not a reliable way to tell them apart. Check the accompanying instructions to confirm whether the information is meant for Subscribe or direct server import. Do not use an account management webpage as a subscription URL, or enter a single server’s domain as a subscription URL.

In Home, use the add control in the upper-right corner to open Add Server. Find Type and select Subscribe. The layout may change between app versions, so follow the current English labels. Paste the complete subscription URL into URL, then add a note that makes the entry easy to identify. For example, “Personal daily use” describes its purpose without exposing access credentials. After saving, return to Home and check that the subscription and its server entries appear. If only the URL was saved and no content has been retrieved, run a manual update.

Spaces or line breaks before or after the URL, and characters replaced by a messaging app, can cause retrieval to fail. After pasting, check that the query parameters after the question mark are complete, punctuation has not been substituted, and no explanatory text was copied along with the URL. Query parameters may grant access; do not remove them to shorten the displayed URL or paste them into a public online decoder. When checking the URL, compare its beginning, end, and parameter names. There is no need to show the full URL on a shared screen.

After saving, check the subscription group and current selection

Once the subscription content appears in the app, check that it is in the expected group and that the server names, protocol types, and number of entries match your source information. A name is only a note; it does not prove that two entries are identical. Entries with the same name may use different ports or transport settings. For a first import, select an entry, open its details, and check the basic fields. Then return to Home and confirm which entry is selected. Do not skip the required Config selection or system authorization just because the list is visible.

Subscribe keeps the remote collection linked to the local list for ongoing maintenance; it does not turn every entry into an unrelated manually configured item. An update may add, remove, or replace servers in the collection. If you edit parameters on an entry created by a subscription, a later update may overwrite your changes. For temporary troubleshooting, note the original values first. If you need to keep custom details long term, manage them as a separate entry if the app allows it, and remember that it will no longer be maintained by the original subscription.

Troubleshoot import failures by stage

If the app rejects the URL when you save it, first check the URL field and its format. If saving succeeds but retrieval fails, check whether the endpoint is accessible, authorization is still valid, and the response contains the expected content. A remote service may return a login page, an information page, or empty text. A browser may still report that the request succeeded, but those responses are not a parseable server collection. Do not assume the app has a parsing problem just because the page opens. Confirm from your source information that the URL is a subscription endpoint, then compare the app’s error message.

When troubleshooting, change one condition at a time. Copy the original URL again and retry the update. If it still fails, compare the results on Wi-Fi and cellular, and note which stage fails. Avoid repeatedly deleting and recreating entries; doing so loses the context of their groups and current selection. If the old list still works, keep it and pause further changes until you have confirmed the remote content. For the full first-connection sequence, see Getting Started. To look up a specific error, visit Troubleshooting.

02 · Add Server: Check each field when entering details manually

Select Type before filling in the general fields

Use Add Server to create a separate entry from complete details for an existing server. Select Type first, then fill in the relevant fields; the protocol determines which parameters are needed. Do not fill in the default form and then switch protocols at random. Some fields may no longer apply after switching, and required fields may need to be checked again. If you only have a subscription URL, use the Subscribe workflow instead of guessing server parameters from the URL.

Enter the server’s domain or IP address in Address and the specified port in Port. Unless the field explicitly requires a complete URL, do not include a protocol prefix, path, or port in Address. Hyphens and digits in domain names are easy to mix up when copying, and you should not guess a Port based on convention. A server name or note is for local identification; it usually is not used for authentication. Changing the note will not fix an incorrect address, password, or transport parameter.

Authentication details must match the selected protocol. Some protocols use Password, while others require a UUID, username, key, or other protocol-specific fields. Whitespace is part of the actual value, so watch for line breaks copied from the end of a document. Compare every field with the original information before saving and testing. If details are missing, obtain them before proceeding rather than filling gaps with fields from another protocol. The goal of manual entry is to accurately reproduce the information you already have, not to try every option until something connects by chance.

Check protocol fields and transport fields separately

Protocol authentication and transport settings are separate layers. Two VLESS or VMess entries may use different transports. Even when Address, Port, and UUID match, a missing path, Host, or TLS parameter can prevent a connection. Only enter additional values when your source information specifies them; do not fill a field simply because it appears in the form. Check the authentication details first, then the transport settings, and finally the certificate settings to avoid confusion from repeated changes.

The TLS server name is used for certificate verification and related steps. It does not always have to match Address, but it must follow the server configuration. If you see a certificate error, do not start by disabling verification to bypass it. Check the domain, device time, certificate validity, and the required server name in your source information. Some errors that look like a connection failure actually occur during authentication or the handshake. Keeping the exact error text is more useful than noting only whether the connection switch was on.

Save an entry you can review later

Before saving, check the fields in this order: address and port, authentication, transport, TLS, and note. After saving, return to Home, select the entry, and confirm that it is selected before testing. A successful save does not mean the connection works: form validation checks only some formatting and cannot confirm that the remote server is accepting requests. If imports and manual entry produce different results, open the details and compare each field, paying particular attention to default values and parameters not included in the share link.

If you need to test a field, copy the entry or save its original value first. Change one item at a time and record the result. If you change several things at once, it is difficult to know what fixed the connection, even if it works again. For subscription-managed servers, check whether the remote information needs to be updated before making a lasting correction; a local change may be replaced at the next refresh. For an explanation of Hysteria2 transport, see Hysteria2 Protocol Explained. Enter server details according to the information you already have.

03 · Scan QR Code and clipboard imports: Preview before saving

Scanning changes how you enter information, not your responsibility to check it

Scan QR Code reads the text encoded in a QR code. The app then determines whether it can process that text as server or subscription information. Before scanning, confirm that the code comes from information you already have and determine whether it represents one server or a subscription endpoint. QR codes can look alike while containing entirely different data. Account webpages, plain text, and server share links can all be encoded as QR codes, so a successful scan means only that the content was read—not that it is a valid configuration.

Open Scan QR Code from the scan control in Home, grant camera access if prompted by the system, and fit the complete code within the viewfinder. If the app displays details or an import confirmation, pause to check Type, Address, Port, and the note before proceeding. A cropped, compressed, or reflective QR code may not scan correctly. Improve the image clarity and camera distance, then try again; a scan failure does not mean the server is unavailable.

If the QR code is saved on the same device, use a photo library option only if the current app interface provides one. If it does not, there is no need to keep searching. A more direct option is to import the original share text from your source information using the clipboard. Do not upload an image containing credentials to a public recognition tool or display a complete QR code on a public page. QR code contents can grant the same access as the corresponding plain-text credentials.

Preserve the complete text when importing from the clipboard

Copy only one complete share link or one clearly identified subscription URL. Do not include a title, item number, quotation marks, or explanatory text. Return to Shadowrocket and use the clipboard import or add prompt available in the current interface. If iOS asks for permission to paste, confirm that you intend to read the information you just copied. If no import prompt appears, check the add workflow for an appropriate option. Do not paste a whole encoded string into the Address field.

Long links may wrap automatically on screen; a visual line break is not necessarily part of the text. The real issue is usually that the link was truncated, spaces were inserted, or only the visible link title was copied instead of its underlying content. If import fails, return to the original source and copy the text again. Do not manually remove encoded sections you do not recognize. If the information comes from a document, copy it as plain text to avoid smart punctuation replacing quotation marks, plus signs, or slashes.

When importing multiple items at once, first confirm how the app handles the format. Multiple lines of share text are not the same as an encoded collection returned by a subscription; do not use the same import path simply because both contain several servers. Import one entry you can verify first, then process the rest. After importing, check which group the new entries belong to so they are not confused with existing items of the same name when you select a server later.

Check scanning, parsing, and connection separately

Break the process into three checks: first, was the complete text read? Second, was it parsed into the correct entry? Third, can that entry establish the expected connection? A scan with no response is usually a first-stage issue. An unsupported-content message usually points to parsing. If the entry appears but requests fail, investigate the connection stage. Troubleshooting by stage avoids rescanning repeatedly without ever checking Port or TLS fields.

After parsing succeeds, open the new entry’s details and compare them with your source information. A garbled name may be a note encoding issue, or it may indicate that the link was encoded more than once. Check the authentication and transport fields rather than relying on the name. If QR and clipboard imports produce the same entry but both fail to connect, focus on the original parameters, server status, and local network instead of switching import methods again. Keep one entry; importing duplicates will not improve the chance of connecting.

After importing, you can overwrite sensitive clipboard contents with ordinary text and manage clipboard access through your device’s privacy settings. If you shared your screen or sent a screenshot during the import, check whether it exposed a complete QR code or authorization parameters. Before deleting an incorrectly imported entry, make sure it is not the one currently in use. Then follow the Deletion and backups section of this guide. A first connection also requires selecting Global Routing and completing system authorization; the Getting Started guide explains these steps in order.

04 · Shared link formats: Distinguish entries, subscriptions, and Config

The protocol prefix determines how the rest of the text is interpreted

An individual server share link usually has a protocol prefix, such as ss://, vmess://, vless://, or trojan://. These are not ordinary webpage URLs; they tell the app how to interpret the server information that follows. Each protocol has its own encoding and parameter conventions. Some put several fields in encoded content, while others express authentication, addresses, and query parameters separately. Do not change a link from one protocol to another by replacing its prefix.

An HTTPS URL’s appearance alone does not tell you what it is for. It may point to a subscription, a configuration file, or simply a webpage. Before importing, use your source information to identify the intended item: use the server import workflow for server details, Subscribe for a subscription endpoint, and Config for rule settings. If you parse Config text as a server list, or load a server subscription as a configuration file, the error is usually in content parsing, not network connectivity.

Text after a hash in a share link is often a note, while text after a question mark often contains additional parameters; follow the conventions of the specific format. Changing a note usually will not fix authentication, but query parameters may affect transport, paths, or TLS behavior. Do not remove the latter part just to shorten the link, or replace encoded characters with ones that look easier to read. When percent encoding, Base64, and plain text are mixed, decoding more than once can change the actual field values.

Understand what a .conf file does—and does not do

A Shadowrocket .conf file can contain rules and other configuration settings. The example below shows only a [Rule] section. The domain is for illustrating syntax; it is not usable server information or a complete configuration for establishing a connection. The rules describe how requests should be handled, not where server credentials come from. If you use an existing configuration, keep the original file and check how its rules relate to the other settings. Do not replace the entire active configuration with just these three lines.

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

DOMAIN-SUFFIX matches domain suffixes, GEOIP matches a target IP by geographic classification, and FINAL defines the final handling rule. Rules are usually evaluated in order, so the position of specific and fallback conditions matters. PROXY and DIRECT are rule action keywords; do not translate them. example.com here is only an illustrative match target, not a value to enter in a server entry.

Config, Proxy, and Direct under Global Routing determine how requests are handled overall. With Config selected, check the active configuration and its rules. With Proxy selected, a website loading successfully does not prove that a domain rule is correct. With Direct selected, the result does not prove that a proxy server works. Check subscription management and rule configuration separately: confirm the current entry, then the routing mode, and finally whether the actual request followed the expected path.

Check the scope and sensitive information before sharing

Sharing a single server entry and sharing an entire configuration can expose different amounts of information. An entry may contain authentication details; a configuration file may include custom rules, DNS settings, remote URLs, and other personal settings. Before sending anything, decide what the recipient actually needs. A redacted screenshot can show field names for troubleshooting, and a minimal rule snippet can illustrate a rule. There is no need to send all account-related information. Even if the note looks harmless, the link itself may provide direct access.

When moving details between your own devices, use the app’s sharing feature if available, then check the imported result on the receiving device. Generating a link does not complete the transfer. Some additional settings may depend on a local configuration or subscription relationship, and an individual share link may not carry all that context. In particular, a standalone entry shared from a subscription may no longer be maintained by that subscription. Check the imported group and source rather than assuming that matching parameters mean the maintenance relationship is also preserved.

If a format is not recognized, keep the original text and check whether the app supports that format. Do not paste it into a public conversion service. Obtain a version in a format supported by the import workflow from your existing source information, or use Add Server if you have all the required fields. For protocol-specific extensions, follow the current app interface and original server details. This guide does not guess authentication fields by modifying encoded text or explain how to reconstruct missing credentials.

05 · Update settings: Distinguish a successful fetch from changed content

Run a manual update you can verify

A subscription update requests the subscription endpoint again and applies the returned server content to its collection. It does not repair every server or restore expired authorization. Before updating, note the subscription group and selected server you are using, and, if necessary, the active Config. That way, if the list order or names change or an entry disappears, you can identify what changed instead of assuming the update erased your client settings.

Find the subscription in Home and use the update action available in the current interface. Depending on the layout, it may be in a group menu, an edit screen, or subscription management. Update the Subscribe object, rather than editing each server entry. Wait for the request to finish before checking the feedback and list. Do not tap repeatedly while it is still in progress. If you have multiple subscriptions, update one known collection first and check the result before proceeding, so you can identify which endpoint is causing a problem.

An update can succeed without changing any entries if the remote content matches the local list; more entries do not necessarily mean a better connection. Check four things separately: whether the request completed, whether the content was parsed, whether the changes were expected, and whether the current selection is still valid. After updating, open a frequently used entry and check whether its protocol or key parameters changed, then run a test. If the selected entry was removed, choose another one from the updated collection. The connection switch staying on does not mean the old selection is still valid.

Automatic updates and request routing

To automate maintenance, look for subscription update options in Settings and follow the current interface instructions—for example, updating when the app opens. First confirm the subscription endpoint with a manual update, then enable automatic updates. Automation changes when the request is triggered; it does not guarantee that a network request will complete in the background. Device connectivity, app state, and system scheduling can all affect the result. After an important change, check the subscription list instead of relying only on the switch.

Update requests also need a network route. If the subscription endpoint is accessible only under certain connection conditions, use your existing configuration to understand which route the request takes. Do not immediately switch all traffic to a different Global Routing mode. If an old server no longer works and the update request depends on it, you may get stuck in a loop where you cannot fetch a new list. Note the routing mode and network conditions before and after each change. Change one condition at a time to avoid permanently disrupting your usual rules just to update a subscription.

Preserve the current state after a failure; avoid rebuilding entries

If an update fails, keep the subscription and old entries in place and record the error text and network conditions. If the old list is still there, do not delete it immediately. Deletion will not change what the remote endpoint returns and may remove useful reference entries. First check whether the authorization parameters are complete and whether the endpoint has changed; then decide if the URL needs replacing. Replacing an endpoint and adding a second subscription have different results, so be clear whether you are correcting the existing collection or creating a separate one.

If many entries change after an update, check whether you used a different existing subscription URL or copied an address intended for another purpose. Do not rely on the note alone: two entries can have the same note and entirely different URLs. If the remote content has changed, whether old entries still work depends on the server’s status. Keeping them helps with comparison but does not mean they remain valid. Check against the new information and avoid adding obsolete entries back into a collection that is meant to stay maintained.

For routine maintenance, use a clear cadence: check manually when needed, use automatic updates as a convenience, and keep a complete record of failures. Repeated, frequent requests will not fix a format problem and can make error feedback harder to interpret. For details on update controls and troubleshooting paths, see Manual and Automatic Subscription Updates. If parsing succeeds but performance is slow, go to Tests and sorting rather than treating it as a subscription format issue.

06 · Organize multiple subscriptions: Keep ownership clear and rules readable

Use names to describe purpose, not as unique identifiers

If you have multiple subscriptions, first define what each endpoint is for, then organize its server entries. A subscription note can describe its purpose, device, or ownership—for example, “Personal use” or “Temporary testing”—but should not include full authorization details. Server names may come from remote content and can change during updates, so they are not permanent identifiers. Check the relationship between the subscription, protocol, address, and key connection parameters instead.

Before organizing, list your subscription URLs and identify which entries were added manually and which came from a scan or clipboard import. Servers with the same name are not necessarily duplicates, and entries with different names may point to the same address. Do not delete entries in bulk based on names alone. Open the details to compare Address, Port, Type, and transport parameters, then decide whether an entry is truly redundant. Keep entries with different authentication details unless your source information confirms one is no longer needed.

Importing the same subscription more than once usually creates duplicate items to maintain, not a more complete collection. Choose which one to keep based on its current selection, note, and references in Config—not simply because it appears first in the list. Before deleting duplicates, select and verify the corresponding entry in the collection you plan to keep. This helps prevent accidental deletion of the only working entry, even when several items share a name. Keep cleanup separate from updating so you can tell what caused each change.

Subscription groups are not routing policies

Subscription groups in Home answer “which endpoint maintains these servers?” Rules in Config answer “how should this request be handled?” Putting servers in different subscriptions does not automatically route different websites through each one. If your configuration uses policy groups or references specific names, check how it actually selects a server. Changing the display order alone does not modify the rule match conditions.

Global Routing is the place to start when checking this relationship. With Config selected, confirm which configuration is active, then check its rules and policies. With Proxy selected, tests use the proxy route; with Direct selected, results reflect a direct connection. Do not reorganize subscriptions while changing routing modes without keeping a record. Tests on the same server may use different request paths, making comparisons unreliable.

Use small batches to keep long-term management clear

Organize in this order: confirm ownership, check for duplicates, standardize notes, verify the selection, then remove unnecessary entries. Work on one subscription at a time. After each group, return to Home and check the list before moving on. If the app offers filtering, collapsing, or sorting, use those display options to reduce clutter before deleting anything. Hiding or collapsing changes what is visible; deletion changes what is stored. They are not interchangeable. Before any bulk action, check whether it applies to the current group or all entries.

Use a separate naming convention for manually entered entries you plan to keep, making clear that they are not maintained by Subscribe. Describe their purpose in the note rather than using test numbers that may quickly become outdated. If you are comparing two parameter sets temporarily, note which is “original” and which is “test,” then remove the temporary entry when you are done. Do not leave an unrecorded change in a subscription-generated entry; a later refresh may overwrite it, and someone troubleshooting later may mistake it for the original remote information.

After organizing, check the selected entry and any references in Config. If the configuration refers to entries by name, renaming or deleting one can affect later selection. A tidy list alone is not enough. Be especially cautious about relying on fixed display names in collections where names may change during updates. For more on rules and routing modes, see Proxy Modes. If list management is working but a website is handled incorrectly, check the rules instead of continuing to rearrange subscription groups.

07 · Connectivity Test: Test, sort, and verify actual requests

First, confirm what the test measures

Interpret Connectivity Test results in light of the selected test method. Some methods check whether a server address and port are reachable; others send a specified request through the proxy. They cover different stages. A successful basic network probe does not prove that protocol authentication, the TLS handshake, and access to the destination website all work. Check the method and relevant settings in the current interface before interpreting the result. No single number is a complete measure of connection quality.

Keep test conditions as consistent as possible: use the same device, network, and test method, and avoid updating subscriptions or transferring large amounts of data at the same time. If you test one entry on Wi-Fi and another on cellular, local network differences affect the results. Batch tests can also be influenced by concurrent requests, so small differences in the list may not matter in practice. Start with entries that clearly fail or behave consistently poorly, then repeat the test with a small number of candidates.

If a test times out, first identify which kind of test failed. An unreachable server port, failed protocol authentication, and an unreachable test target can all appear as failures, but require different troubleshooting. Do not delete every entry that times out without checking the test method. Choose one entry whose parameters you have verified, compare basic connectivity with an actual request, and review the error messages. This makes it easier to identify the failing layer than repeatedly changing test targets.

Sorting is a diagnostic tool, not a lasting guarantee

Sorting by test results can narrow down your options, but it reflects one observation under the current conditions. Network load, destination, connection reuse, and test timing all affect the results. The first entry in the list may not work best for every request. Do not record a single low latency value as permanent, or treat it as proof of sustained throughput. For regular use, repeated consistency and the results of actual requests matter more.

After sorting, confirm the selected server manually. Changing the display order may not change the selection, and completing a batch test does not mean the client automatically uses the best result. If your Config includes policy groups or other selection logic, check how they behave. When you are done, return to Home, check the current entry, and make an actual request. Do not assume a server is active just because it appears first in the sorted list.

Close the loop by testing an actual request

After a test passes, check a request you actually need and confirm Global Routing and the active Config. If ordinary browsing works but one app does not, check the destination domain, DNS, rule matching, and the app’s own connection behavior instead of changing every server parameter. Existing connections may continue to use their original route. After switching servers, use a new request to check for a change; an existing connection does not show whether the new selection is active.

If real-world access is slow, compare the server, transport route, local network, and destination service one layer at a time. First try another existing entry on the same network, then compare Wi-Fi and cellular if possible. Keep the request the same and change only one condition at a time. If only domain-related requests fail, check DNS and rules; if all connections are unstable, start with the local network. For a step-by-step breakdown, see How to Troubleshoot Slow Speeds by Layer.

When asking for help, include the protocol, test method, failure stage, current Global Routing mode, and network conditions. Do not include Password, UUID, or a complete subscription URL. For DNS issues, see DNS Settings. Do not change DNS, rules, and servers all at once just to improve one test result. Each test should answer one question so you can make informed changes. When results vary, a few controlled repeats are more useful than repeated bulk refreshes.

08 · Deletion and backups: Verify recovery before cleanup

Before deleting, confirm the item and scope

Deleting a manually entered server, a subscription, and a Config are three different actions. Deleting a single entry usually affects that server. Deleting a subscription may remove the collection it maintains. Deleting a configuration file affects its rules and related settings. Read the current confirmation prompt to understand the scope before proceeding. Items shown next to each other may not be recoverable in the same way. Do not mistake leaving an edit screen for canceling a deletion.

Before deleting an entry in use, select another existing entry that you have verified and confirm that the current configuration still works as expected. If there are policy references or fixed-name dependencies, check whether they need updating too. A locally deleted entry in a subscription may reappear at the next update if it is still in the remote content. If you only want to reduce clutter, first check the app’s organization options rather than treating deletion as a permanent filter.

Before removing duplicate subscriptions, compare their endpoints and ownership, then back up any local information you need to keep. Matching group names do not guarantee identical content, and similar-looking URLs may have different authorization parameters. For an old endpoint you no longer use, first confirm that the replacement has updated successfully and passed an actual connection test. Keep a brief record of what you removed and what replaced it to make migration or recovery easier.

Back up each type of information separately

A backup should cover four types of information: subscription URLs and notes, independent server parameters, the active Config, and any essential local settings. An app purchase record does not back up this information. Getting Shadowrocket again from the App Store does not automatically restore your personal configuration. The backup or export features available in the current app determine what can be saved. Check what is actually included instead of assuming that a filename means it contains everything.

If the current interface provides a Data or other backup option, follow its instructions and check whether the export includes the items you need. Save anything that must be handled separately: keep the original subscription details, save independent configuration files, and record manually entered fields and selection relationships. Do not put sensitive parameters in public notes or casually shared folders. Treat backup files as access credentials and store them somewhere you control with appropriate protection.

Record the context with your backup: which Config is active, the Global Routing selection, which subscription contains commonly used entries, and whether subscription auto-update or On Demand is enabled. An individual share link may not include all of this information. On Demand can establish connections under specified conditions. After a migration, recheck those conditions and system authorization; do not rely on On Demand before verifying the servers and rules. A useful backup preserves the management relationships needed to understand the imported text, not just the text itself.

Recovery order and backup verification

First, confirm that Shadowrocket was obtained from the App Store. For purchase and reinstallation details, see Restore Purchases. Then follow this order: import subscriptions and independent entries, restore Config, check local settings, select the current entry, and verify an actual request. For subscriptions, inspect the backed-up content before deciding when to update. Updating immediately may change the list and make it harder to compare entries with the old device.

A saved backup file is not necessarily a complete, restorable backup. At an appropriate time, test it in a controlled way: confirm the app can read it, all required entries are present, Config is available, and sensitive fields are intact. If you test on another device you own, avoid overwriting its existing configuration. Keep its original state first, then restore the backup. When finished, compare key fields and test an actual request; matching list counts alone do not prove that recovery is complete.

If a subscription URL or authentication details have changed, an old backup may still contain the old values. Update your backup after important changes are complete and verified, and clearly distinguish the current copy from historical versions. Keeping old data can help with comparisons but does not mean an old server remains usable. If a complete subscription URL or authentication detail has been exposed, deleting the local entry will not revoke access. Manage the affected credentials through the account provider’s existing process, then update the client and backup.

To go through the connection steps again, return to Getting Started. To look up a specific error, visit Troubleshooting. Routine maintenance rarely requires rebuilding the entire configuration. Clear records of endpoints, fields, and changes make it easier to identify which layer caused the next issue.