Shadowrocket
Subscription and Server Management Guide
Find instructions by task: identify subscriptions, servers, and Config first, then handle imports, updates, tests, and backups. This guide assumes you already have your own subscription or server details and does not cover where to obtain them.
For first-time setup, start with the user guide to import your data, choose Global Routing, and verify the connection. This page covers field requirements, troubleshooting, and ongoing maintenance. See the App Store guide for purchasing the app and confirming you have the genuine version.
Subscribe: Check the item and entry point before importing
A subscription URL is not a single server address
A subscription is a remote URL used to retrieve a list of servers. The app requests that URL and parses supported content into local entries; connecting to a server is a separate process. A successful subscription refresh does not mean every listed server can connect, and a server that works temporarily does not prove the subscription URL is still valid. Track these two processes separately when troubleshooting.
A single server entry typically includes a protocol, hostname, port, and authentication details. A subscription URL is usually a full URL with a path or query parameters. Do not paste an entire subscription URL into a server's host field, or mistake a server's domain for a subscription URL. Identify what your existing details describe before choosing an import option to avoid saving an entry with no usable content.
Open Subscribe from Add Server
On Home, open the add menu and select Add Server. Choose Subscribe under Type, paste your existing subscription URL into the URL field, add a recognizable remark, and save. The layout can vary by device; look for Type set to Subscribe and a field for a subscription URL, rather than fields for a single server's authentication details.
After pasting, check the entire URL from beginning to end, especially for a trailing period, parentheses, line breaks, or leading or trailing spaces copied from a message. Letter case, slashes, percent signs, and query parameters may all matter; do not edit them just to make the URL look neater. If your details specify a dedicated subscription URL, use the complete URL—not an account page, help page, or arbitrary URL open in a browser.
https://example.com/sub?token=xxxxThe address above is a fictional structural example and cannot be used for an actual import. Use your own complete URL, and do not post it in public forums. A subscription URL containing credentials should not be shared alongside your account password or publicly synced as a bookmark. Anyone who can access the URL may be able to retrieve its server details.
After saving, check the list—not just the confirmation message
Return to Home and check that the subscription group appears, servers have populated it, and the protocols and remarks match your expectations. If the subscription name appears but no servers are listed, first check whether loading has finished, then whether the returned content could be parsed. Do not keep adding the same URL in an attempt to fix the issue; that can create duplicate groups without addressing the cause.
If servers appear, choose one you are authorized to use and verify the connection. The goal is not to sort every server yet, but to confirm that the imported fields are complete and the authentication details work. Before connecting, check the current Global Routing selection. Importing a subscription does not explain how each rule in a Config file handles traffic.
Initial setup may also prompt you to authorize adding a VPN configuration in iOS. This system step is required for connecting and is separate from checking whether a subscription URL is valid. Verify the app and the source of your details before responding to system prompts; an authorization prompt alone does not mean the subscription was parsed successfully. For the full first-connection sequence, see the user guide.
If the first refresh fails, keep your existing entries and note whether the failure occurred during saving, fetching, or connecting. Then check whether your current network can reach the subscription host and ask the source of your existing details to confirm that the URL is still valid. Identifying the failed stage before changing anything makes troubleshooting clearer and helps avoid deleting entries that still work.
Add Server: Check each field against the protocol
Choose Type before entering the address and authentication details
Manual entry is useful when you already have complete server details and need to maintain a single entry independently. In Add Server, choose Type first, then fill in the fields shown for that protocol. Protocols use different authentication methods; do not reuse a password, identifier, or transport setting from one protocol in another. Similar protocol names do not mean their fields are interchangeable.
The host field usually takes a domain or address, and the port field takes the corresponding number. Unless a field explicitly asks for a URL, do not add a URL scheme to the host or include a path, port, and query parameters in it. When copying details, check the separators carefully, especially in addresses containing colons. Combining the address and port into one field can produce unexpected results.
| Parameter | What to check | Common mistake |
|---|---|---|
| Type | Match the protocol of the existing server | Guessing the protocol from its name |
| Host and port | Enter the connection address and numeric port separately | Including a path in the host field |
| Authentication details | Preserve the password or identifier exactly as specified for the protocol | Dropping characters while copying |
| TLS and SNI | Match the certificate and hostname requirements provided for the server | Using the remark as the SNI value |
| Transport settings | Check the transport type, Host, and path individually | Entering only the address and authentication details |
Check authentication and transport settings separately
For Shadowsocks, check the encryption method and password. For VMess and VLESS, verify the relevant identifier and transport settings. For Trojan, check the password and TLS requirements. Hysteria2 and WireGuard also have their own parameters; a server domain alone is not enough to configure them. If a field is unclear, refer to the details you already have instead of filling it with a guess.
Copy passwords and identifiers in full. Do not remove symbols that look unnecessary or use a remark as authentication data. Some fields obscure their contents, so check the length and first and last characters in a secure setting before saving. When taking screenshots for your records, hide all authentication data—not just a few characters in the middle. Even partial credentials can reveal sensitive information.
TLS, SNI, Host, and path are separate fields. The connection address locates the server; SNI is used during TLS hostname negotiation; Host and path may be part of the application-layer transport request. Keep these values separate even if they look similar in your existing configuration. Do not disable certificate verification just to make a test pass; doing so changes the security boundary and can hide a hostname or certificate configuration error.
With transports such as WebSocket, a missing path or incorrect Host value may allow the address to respond but prevent the connection from completing. Troubleshoot in order: confirm the server protocol, check authentication, then verify transport fields. Change only one confirmed incorrect value at a time and keep the original details for comparison. This makes it easier to identify what caused a change.
Keep manual entries clearly distinct
A remark helps identify an entry; it is not part of the connection protocol. Use it to note the purpose, location, or maintenance approach, but never put a password in it. Use distinct naming conventions for manual entries and subscription-generated entries, such as clearly marking entries you maintain yourself. That makes similar names easier to distinguish after a subscription update, so you can check the right record rather than assuming both entries are identical.
Check five categories before and after saving: Type, host, port, authentication, and transport. Saving usually means the app accepted the fields; it does not confirm that the server considers them correct. You still need to test the connection and check whether access works as expected. If only some sites fail, do not immediately re-enter all server details; first check routing and DNS.
Manual edits to subscription entries may be replaced by content generated during a later refresh. If you need to preserve customized parameters, first confirm whether you are editing a subscription entry or creating an independent manual entry. Choosing independent maintenance also means you are responsible for updating its parameters when the server changes; do not expect a subscription refresh to maintain that separate copy.
If a protocol field is unclear, check the term in the glossary, then refer to your existing server details to fill in each field. This guide does not recommend guessing the protocol, combining fields at random, or repeatedly changing certificate settings. Manual setup depends on complete, matching, and still-valid parameters.
QR codes and clipboard: Check the content before saving
A QR code is only a carrier for information
Scan QR Code reads the text encoded in a QR code. It may be a server share link, a subscription URL, or an ordinary webpage. A successful scan only means the image was recognized; it does not prove the content is suitable for import. Before proceeding, confirm that the QR code belongs to your own server or subscription details and whether it represents one entry or a group of servers.
Open Scan QR Code from the scanning option on Home, respond to the system camera permission prompt, and fit the entire QR code in the viewfinder. Codes that are too small, reflective, cropped, or compressed may not scan reliably. Adjust the distance and brightness and hold the image steady; there is no need to switch rapidly between options. If the code is displayed on another device, enlarging it is usually more reliable than repeatedly cropping a photo.
If the current interface offers QR scanning from Photos, you can select the original saved image. If not, scan with the camera or use an existing text link. Do not grant unrelated permissions just to look for a button that is not available. Keep the full border around QR codes in images; cropping too close to the pattern can reduce error correction.
Handle permissions and scan results
If camera access is denied, check the app's permissions in the relevant system settings, then return to the scanner. A permissions issue and invalid QR content are different problems: the first prevents camera use, while the second usually occurs after text has been read. Distinguishing them avoids recreating server details to fix a local permissions issue.
After scanning, check the import preview or newly created entry for Type, address, port, and remark. If the result is a subscription, check whether a server list is fetched afterward. If it is a single share link, confirm the server was added where expected. Do not judge the contents solely by the title beside the QR code; the surrounding text may not match what is encoded.
Clipboard imports: Preserve the complete original text
To import from the clipboard, first copy one complete share link you already have, then return to Shadowrocket and use the import option available in the current interface. If the system asks for permission to paste, decide based on your own action. Do not copy an entire message with explanations, chat names, and punctuation. Identify exactly where the link starts and ends before importing it.
Long text can be truncated at the end or copied with line breaks that only appear in the display. Check that the link prefix is complete, that it does not include curly quotation marks, and that a chat app has not truncated its display. A link shown with a short title may not have copied its full address. If needed, use the copy function explicitly provided with your details and inspect the result in a secure local setting.
After importing multiple share links, check the number of new entries and their protocol types. If one link is unsupported, do not assume the entire batch imported just because some entries succeeded. Do not paste everything again to make up for an unknown missing entry; compare against the original list, identify the missing item, and handle it separately to avoid duplicate servers.
Narrow down import failures by stage
If no text was read, check camera permissions, image quality, and the QR code border. If text was read but not recognized as a server, check its format and completeness. If an entry was created but cannot connect, troubleshoot the parameters and network. These are different stages with different checks; do not label every failure as an invalid QR code or delete all existing subscriptions.
After importing, remove temporary images and clipboard contents you no longer need, especially if your device syncs them elsewhere. Deleting a temporary copy does not revoke server credentials. If a QR code or link has been exposed, ask the source of your existing service how to replace the relevant credentials, then update your local entry. Simply deleting the image is not enough.
When importing for the first time, keep old entries until you have verified the new ones work. For entries with the same name, compare protocol, host, and port rather than relying on the remark alone. For a basic connection, follow the quick-start steps in the user guide. This chapter covers edge cases such as recognition failures, permissions, and duplicate imports.
Subscription updates: Separate requests, parsing, and connections
After a manual refresh, check what changed
Refreshing a subscription requests its existing URL again and updates the associated server list with the returned content. It does not update the app or reset all settings. Before refreshing, note the entry and group you are currently using so you can identify changes in names or order. If your current connection is important, choose a convenient time to check the results.
Find the subscription on Home and use its corresponding refresh option; the button or menu location depends on the current interface. Afterward, check that the group is still there, the number of entries is reasonable, and whether you need to confirm your current selection again. Do not exit as soon as a refresh starts, and do not assume that no new entries means it failed—the remote list may be unchanged.
The remote content may change server names, addresses, authentication details, or available entries. After refreshing, verify your commonly used servers, especially if an entry was removed or renamed. If rules or policies refer to a specific name, check that the reference still points to the intended target. A list being present does not mean every dependent configuration stayed the same.
Set automatic updates to fit your routine
If Settings or the subscription settings offer an option such as updating automatically when the app opens, enable it if it suits your maintenance needs. Automatic updates can help prevent lists from going stale, but still depend on the network and remote response at the time. The option does not mean updates continue while the app is closed, or that every request will complete in the background.
You can use automatic updates for routine maintenance and refresh manually after a confirmed remote change, an entry stops working, or before moving to another device. Repeated refreshes in a short period usually cannot fix an incorrect URL and may trigger request limits. When an error appears, identify the failure type before trying again instead of repeating the operation until the list changes unexpectedly.
| Failure stage | Check first | Next step |
|---|---|---|
| Could not make the request | Network, DNS resolution, or access route | Retry once on a working network |
| Access error returned | URL validity and credential status | Check your complete URL |
| Response could not be parsed | Whether it is a webpage and whether its format is supported | Confirm it contains subscription data |
| Connection fails after refresh | New parameters, current selection, and rule references | Test the target server by itself |
Keep working entries if an update fails
If existing servers still connect but a subscription refresh fails, keep the current entries for now. This means the connection parameters still work, but the request used to retrieve the list encountered a problem. Deleting and recreating the subscription could remove your only working local entries. Check the original URL, network, and remote response before deciding whether to replace the subscription.
The response may be a sign-in page, an error message, or a maintenance notice. A successful network request does not guarantee that the response can be parsed as a server list. A page opening in a browser only proves the browser received webpage content; it does not prove the app received the right format. Confirm that the URL is specifically for a subscription, not an account page or a regular webpage reached after a redirect.
If you suspect credentials have expired, check their status through the management method for your existing service; do not try to restore access by changing random characters in the URL. After changing the URL, verify that the new one returns a reasonable list before removing the old entry. Revoking old credentials is a remote operation; deleting a local subscription does not invalidate them. Handle both separately.
Handle app updates and subscription refreshes separately
Shadowrocket app updates are managed through the App Store; subscription refreshes retrieve content from an existing URL. They affect different things. Updating the app does not guarantee that an expired subscription URL will work again, and refreshing a subscription does not change the app's features. Check the App Store page for system requirements, device compatibility, and purchase details. See How to buy and install the genuine app for verification steps.
For more on the differences between manual refreshes and automatic updates when the app opens, see How to troubleshoot subscription update failures. Maintenance notes need only include the subscription alias, time of operation, error type, and verification result. Do not keep full credentials in a log. This is enough to spot recurring issues and identify the affected subscriptions.
Manage multiple subscriptions: Keep sources and references clear
Define group labels before sorting
When you have multiple subscriptions, make it easy to tell who maintains each entry, which subscription it belongs to, and which entries a refresh may affect. Do not rename all servers similarly and then try to remember their original groups. Give each subscription a stable alias based on its purpose or a category you understand. Do not include credentials or account details in visible names.
A subscription alias describes how you manage it locally; it is not a rating of server quality. You can use labels for work, testing, or maintenance responsibility, but do not treat one speed test as a permanent verdict. Test results vary over time and with the network, while names are often kept for a long time. Putting temporary status in a name can lead to choices based on outdated information.
Keep manual entries distinguishable from subscription-generated entries. If you need to copy a subscription server for independent changes, mark it clearly as manually maintained and keep a secure record of its original parameters. Otherwise, a refresh may update one entry while the other keeps old values, making what looks like one server appear inconsistent when the two entries actually have different settings.
Compare connection details before removing duplicates
Entries with the same name are not necessarily duplicates, and the same host can support more than one connection. Compare protocol, host, port, authentication, and transport settings; check TLS names and paths if needed. Two entries with the same remark may use different ports or authentication. Deleting entries by name alone can remove a separate record you still need.
Conversely, different names can refer to the same connection parameters. Duplicates often come from repeated imports, manual copies, or overlapping subscriptions. First decide which entry to keep for everyday use, then remove redundant copies. Do not delete an entire group just to shorten the list; the group may define how future updates and maintenance work.
Check server selection alongside rule references
The server currently selected on Home may relate to policies or rule references in Config, but the highlighted entry alone cannot show where every connection will go. A rule may specify a policy, and a policy may have its own selection. After organizing the list, check whether commonly used configurations refer to an entry that was renamed or removed, then verify access in practice.
With Config selected in Global Routing, rule order determines how connections are handled. Proxy routes connections through a proxy; Direct connects directly. These modes do not filter subscription groups or merge duplicate servers for you. When maintaining the list, record the mode, current selection, and configuration name together to help explain changes in behavior.
If you are handling an important connection, do not rename subscriptions, delete entries in bulk, and rewrite rules all at once. Organize one group, finish its refresh and tests, then move on to the next. Change one scope at a time so you know what to revert if the result is unexpected. Changing everything at once makes it hard to tell whether a name reference, parameter, or network change caused the problem.
Keep lightweight records without exposing credentials
Management notes can include a subscription alias, purpose, automatic update status, latest check result, and whether a separate manual copy exists. There is no need to record the full subscription URL, and passwords should never go in ordinary notes. If you need to compare devices, use the same non-sensitive alias on both. Match records by name instead of sending valid credentials in a chat.
Check the lists on your iPhone and iPad rather than assuming they are identical because the app uses the same purchase account. Subscriptions, current selections, and Config files may not all be in sync. Restoring a purchase confirms your app entitlement; restoring server details and configuration is a separate process. Before switching devices, check each item using the Deletion and backups section on this page.
When you finish organizing, verify a commonly used configuration and server, then check that refresh still points to the right subscription. Clear boundaries matter more than an extremely short list: if a subscription fails, you need to know which entries it affects and which manual records can still work independently. That lets you troubleshoot without expanding the scope of changes.
Latency tests and sorting: Standardize conditions before comparing results
A test result describes one measurement
Connectivity Test checks responsiveness using the selected test method. The number reflects one measurement for a particular route and test target; it does not guarantee long-term server performance. Low latency does not mean high throughput or fast access to every website. A timeout means only that the test did not complete under those conditions; one result alone cannot prove a server is permanently unavailable.
Different test methods cover different stages. Some focus more closely on establishing a connection, while others also request a test target. Before comparing results, check the relevant test settings in Settings and confirm that the target and method have not changed. Measurements made with different targets or networks are not directly comparable, even if they appear in the same list.
Reduce heavy data transfers on the device during a test, stay on the same network, and test at similar times. Wireless signal strength, local network congestion, DNS resolution, and target response can all affect results. The goal is not a perfect laboratory setup, but fewer obvious sources of interference so repeated tests reflect differences in your actual usage environment.
Test a small set first, then verify real-world use
If you have many servers, start with a commonly used group or a small set of candidates instead of testing every entry each time. A large batch creates concurrent requests that can affect the local network or remote response. If many entries fail at once, check shared network conditions and the test target before treating every server as unavailable.
After an initial screen, test candidate entries more than once and look for consistent results rather than keeping only the lowest number. An entry that fluctuates widely may not suit your needs, even if it occasionally tests well. Then test the connection, DNS resolution, and sustained transfers for your actual use case. A short request does not replace checking stability during a longer task; the two tests answer different questions.
| What you see | Possible causes | How to verify |
|---|---|---|
| All entries time out | Local network or test target | Check shared conditions, then retest a small set |
| One entry repeatedly fails | Parameters, authentication, or server status | Check that entry and test the connection |
| Low latency, but slow transfers | Throughput, congestion, or route to the target | Test the actual task, not latency alone |
| Some targets fail | Rules, DNS, or target status | Check the matched policy and DNS result |
Sorting changes only the display order
Sorting by latency is useful for a temporary view of test results, but it does not promise automatic server switching. List order, the currently selected server, and policy behavior are separate things; confirm the actual selection after sorting. Untested entries, timeouts, and older results may be displayed differently, and should not be treated as stable performance ratings. First check that the results are from the same test run.
After a remote subscription refresh, new entries may have no comparable test results, and existing entries may have changed parameters. Retest when needed rather than relying on old rankings. For long-term tracking, note non-sensitive aliases, network conditions, and general performance. Look for recurring, stable differences rather than treating every momentary result as a permanent label.
Include rules and DNS in your checks
If tests look normal but access does not, first check the current Global Routing mode, then review the Config rules that may match the target. If the target is handled by DIRECT, a test of the current proxy server cannot explain that access. If a specific policy matches, confirm which connection that policy actually uses instead of checking only the entry currently shown on Home.
DNS resolution failures can also make a website unavailable; they do not necessarily mean the server address cannot connect. Identify whether the unresolved name belongs to the subscription host, server host, or access target. Test one layer at a time. Changing servers, DNS, and rules together may temporarily fix the issue but leave you unsure what worked. See DNS settings for a detailed comparison of resolution methods.
For a broader approach to choosing between existing servers, see How to assess latency, region, and protocol. This page covers management of servers you already have; it does not recommend any service based on test results. Choose an existing entry based on your actual task, current network, and repeated observations—not a single lowest measurement.
Deletion and backups: Verify recovery before cleaning up
First identify what you are deleting
Before cleanup, distinguish a single server, an entire subscription, and a Config file. Deleting a server may only remove its local entry; if it came from a subscription, a later refresh may bring it back. Deleting a subscription affects its management relationship and entries, while deleting Config affects routing settings. These actions are not interchangeable and should not be used as a way to reset everything.
Do not delete your only local copy as soon as a subscription refresh fails. First check whether any server still works, whether the original subscription URL is safely stored, and whether you can retrieve the existing parameters again. Deletion usually cannot revoke remote credentials or fix a network request. Clean up only after confirming the entry is no longer needed and checking how to restore it.
Before removing duplicate entries, check whether any rules or policies refer to their names. The server list may look cleaner after deletion, but configurations that depend on those names may need updating. Remove one unused entry first and verify that commonly used configurations still work before widening the cleanup. Bulk deletion is best reserved for cases where backups and reference checks are complete—not used to guess at the cause of a problem.
Back up each type of data you need
Before making a backup, list what you need to keep: subscription URLs, independent manual servers, Config files, and usage-related settings. A subscription URL may retrieve the current remote list, but it does not guarantee recovery of old entries, local renaming, or manual edits. Saving only the subscription URL is not a substitute for checking independent servers and custom configurations.
Use the export or share option available in the current app interface, confirm exactly what it includes, and choose a secure storage location you control. If an option shares only one server, it is not a complete backup. If you export a configuration file, check that it includes the server references needed for recovery. Do not infer the backup scope from the file name.
Verify recovery, not just export success
After exporting, check that the file exists, can be opened, and is stored somewhere you can access after switching devices. For important data, you may keep a second controlled copy, with clear purpose and access limits for both. If the only copy stays on the old device you plan to erase, the export completed but you do not have a backup available for restoring to a new device.
Before restoring, confirm Shadowrocket is installed on the target device through the App Store, then import each type of data separately. Restoring an app purchase and restoring server details are two different processes: one confirms purchase eligibility; the other restores connection data. Check the App Store page for iPhone and iPad system requirements, compatibility, and Universal Purchase details. See How to restore previous purchases for steps.
If the target device already has data, back up its current state before importing older information to avoid overwriting entries or creating confusing duplicates. You can restore one subscription or manual server first, verify its parameters, then restore Config and other records. After importing, check the current selection, Global Routing, and commonly used rules. Do not erase the old device just because the list appears on the new one.
Complete at least one real connection and destination access test, then check that subscriptions can refresh. A server with working parameters does not prove its subscription credentials are still valid; a subscription that refreshes does not prove custom rules have been restored correctly. Verify fetching, connecting, and routing separately before considering the essential setup restored on the new device.
Handle exposed credentials separately from local deletion
If a complete subscription URL, QR code, or backup was made public, replace or revoke the relevant credentials through the management method for your existing service, then update local records. Deleting a chat message, clearing the clipboard, or removing a server does not invalidate copies already made. After replacement, check old backups and other devices so you do not later restore a URL that has been retired.
For ongoing maintenance, follow a consistent order: note the current state, refresh one subscription, verify commonly used connections, remove duplicate entries, and update your backup last. Each change then has a clear scope and can be reviewed. To repeat the initial connection steps, return to the user guide; to identify fields, consult the glossary. Do not clear all data repeatedly instead of troubleshooting one layer at a time.