01 / Subscribe
Subscribe: Add a subscription for the first time
Understand subscriptions, servers and Config
A subscription is an address that can be used repeatedly to retrieve a server list. A server entry contains the parameters used to establish a connection, while Config manages settings such as rules and DNS. These work together but are not the same kind of file. Adding a subscription and seeing multiple servers does not mean the current Config has been replaced. Importing Config and changing rules does not mean a subscription address has been saved. First identify what kind of information you have to avoid entering a Config URL in a server field or mistaking a single share link for a subscription.
Subscription links often contain access credentials, so treat the complete URL as sensitive information. Copy the raw text without selecting the page title, explanatory text, quotation marks or line breaks. Links forwarded in chat may be truncated; do not try to fill in missing characters based on a shortened preview. If you cannot confirm the URL is complete, retrieve the original instead of guessing at its parameters. Get the subscription address from your service provider; the steps below assume you already have it.
Select Subscribe in Add Server
Go to Home and open the add menu. In Add Server, select Subscribe under Type, then enter the complete address in URL. Give the subscription a recognizable name; this is for local organization and does not change its remote contents. After saving, check Home for the subscription group and server list. If the group appears but contains no selectable entries, first confirm the fetch completed, then check whether the response can be parsed. Creating the same subscription repeatedly is not a substitute for troubleshooting.
Keep your existing servers and settings when importing a subscription for the first time. If you already have a working connection, note the selected server and Global Routing setting before adding the subscription. After saving, select one newly imported server and test it on its own. Once the connection and web access behave as expected, organize the old data. If the new address returns unexpected results, you can then fall back to the original entry without having to troubleshoot import, rules and device networking changes all at once.
Troubleshoot import issues by result
Treat a save error, a fetch failure and an empty list as separate issues. If saving fails, check that the URL field is complete and contains no extra spaces. If fetching fails, check the device's current network and whether the address is still valid. If the fetch completes but returns no entries, check the response content type. An address that displays an explanatory page in a browser is not necessarily a subscription URL the client can use. If you see a login page or error message, verify the address's purpose rather than pasting the page text into URL.
Do not judge a successful import by entry count alone. A subscription may contain entries with different protocols, purposes or similar names; some may not work if their parameters are unsupported. Compare a few entries against the information you already have, including names, protocol types, server addresses and ports, then test a connection. If every entry produces the same error, check the common source and import format first. If only one fails, inspect that entry's parameters and remote status.
A successful subscription import creates a local list; it does not verify account status, the remote service or actual access. Distinguish four outcomes: the address can be fetched, entries can be parsed, a server can connect, and a target website can be reached. When contacting your service provider, describe the issue at the relevant stage and hide any credentials in the link. This is more useful than simply saying that the subscription does not work.
02 / Add Server
Add Server: Enter fields and verify the protocol
Choose Type before entering shared fields
Manual setup is useful when you have complete server parameters, need to check a particular entry or want a separate copy for testing. In Add Server, choose Type first, then enter the server address, port and authentication details. The protocol determines what the following fields mean; do not fill them in for one protocol and then switch types arbitrarily. After switching, review all options again, especially authentication, transport and TLS settings, so leftover values do not interfere with the new entry.
Enter a hostname or IP address as the server address; do not include a web page path or query parameters. Enter the port number alone, without a colon or protocol prefix. The name is for identification and is not used for authentication. Including a protocol or transport name in the entry's name will not enable that feature. If the information you received includes only a name, address and port but omits a field required by the selected protocol, get the complete parameters rather than trying a password from another server.
Protocol fields are not interchangeable notes
| Type | Check carefully | Common confusion |
|---|---|---|
| Shadowsocks | Encryption method and password | The encryption method must match the remote server |
| VMess / VLESS | UUID, transport settings and TLS | A UUID alone does not tell you the other settings |
| Trojan | Password, TLS and server name | The connection address may differ from the TLS server name |
| HTTP / SOCKS5 | Authentication requirements, username and password | Enable authentication only if the remote server requires it |
| WireGuard | Keys, address, Peer and routing parameters | This connection type does not use a regular password |
| Hysteria2 | Authentication, TLS and server-specific parameters | Do not copy transport settings from another protocol |
Shadowsocks uses both the encryption method and password for authentication, so changing just one may not fix a connection. VMess and VLESS are different protocols, even though both use a UUID; changing the name does not convert one into the other. Trojan authentication details also cannot be inferred from another protocol's fields. Use the complete parameters provided by your service provider. If a field is missing, confirm whether it has a default instead of filling in a plausible-looking configuration from an unrelated example.
When enabling TLS, distinguish where the connection goes from which name TLS should verify. The connection address locates the remote server; the server name is used for the TLS handshake and certificate verification. They may be the same or may need separate values, depending on the deployment. If a certificate error occurs, check the server name, device time and remote certificate status first; disabling verification is not a general fix. Match transport settings such as Host and path field by field. Capitalization, slashes and encoding can all affect the result.
What to check and change after saving
Reopen the entry after saving and check that Type, address, port, authentication and transport options were retained, then test the connection. Change one category of settings at a time and note the original values. For example, correct the port and test before checking TLS; do not replace every field at once. If you change several things together, even a successful connection will not tell you what fixed it, leaving you to start from scratch the next time the same issue occurs.
Subscription-generated entries and manually added entries need different maintenance. If you rename or edit a subscription entry directly, a later update may overwrite your changes with newly generated content. If you need to keep local changes, create a separate copy if the interface allows it and label it clearly as manually managed. The copy will not follow subscription updates, so you will need to check it yourself when the remote parameters change. Note this in the name and your backup records.
Types such as WireGuard have multiple interdependent parameters. Avoid piecing together a configuration from generic examples if you do not have complete details. Keep keys and authentication fields out of troubleshooting screenshots, public notes and share names. When discussing a field issue, share only the field name, whether it is populated and what error occurs. If you need to compare values, do so through a trusted channel you already use with your service provider; do not post complete connection details publicly.
03 / Scan QR Code
QR code and clipboard import: what to check
A QR code is just another way to encode text
Scan QR Code reads the text encoded in a QR code; it does not determine whether the content suits your needs. A QR code may contain a single server share link, a subscription address or just a regular web address. Before scanning, make sure it comes from your existing server details. After scanning, check whether the app opened a server editor, a subscription editor or another prompt. Recognition alone does not guarantee that the code contains complete connection parameters.
When scanning with the camera, grant the requested system permission and fit the entire QR code in the viewfinder. Avoid clipped edges, strong glare and screen flicker. Adjust the distance and focus before changing other settings. To scan from an image, use a clear original; a small image compressed by a chat app may not have enough detail for a dense code. Being able to view an image does not mean the QR code is still readable.
Check the saved result after scanning
After a successful scan, check that Type, server address, port and name look right. Save, then return to Home to confirm the entry appears. If the QR code contains a subscription, check for the corresponding group rather than a single server with a similar name. A QR code itself does not update over time; only a subscription address saved from its contents can be refreshed. If the code contains fixed server parameters, remote changes will not automatically appear on your device.
Scanning the same QR code repeatedly can create duplicate entries. If you do not see the result right away, check the list, expand the relevant group and review the sort order before trying again. Do not assume a save failed because the new entry is not at the top. If a server with the same name is already listed, compare the address, port and protocol. The matching names could indicate a duplicate or two separate entries; check their parameters.
Keep the original format when importing from the clipboard
Copy a share link from your existing information, return to the app and use the clipboard import option shown in the current interface. If the system asks for permission to paste, decide whether to allow it for this action. If the app does not recognize the content, first check that you copied the complete link rather than a visible page title or shortened preview. Do not insert spaces into a link containing credentials or reformat it to make it easier to read.
When copying several links at once, keep their original line breaks. Numbering, bullet points, Chinese explanations and code fences may also be copied, which can prevent some entries from being recognized. A safer approach is to import one link and confirm its format before handling the rest as supported by the interface. If only some entries import, note which ones succeeded and avoid reimporting the entire text, which may add duplicates.
QR scanning failures and import failures need different troubleshooting. For a scanning issue, check permissions, image clarity and whether the code is intact. For an import issue, check what kind of text was recognized and whether its parameters are complete. If the same link imports when copied but not when scanned, the problem is more likely the quality of the QR code. If neither method works, check the original link format. Changing how the link is carried will not restore characters that are already missing.
Limit how far credentials spread
QR code images and clipboard text can both contain complete authentication details; do not treat them like ordinary instructional screenshots. Do not post a real QR code in a public photo library or forum to demonstrate a step. After importing, you can replace clipboard contents with nonsensitive text and handle images according to your own data storage practices. Clearing one location does not remove synced copies on other devices; check the actual sync scope you use.
If the import option is missing, first check whether you are on Home or another page, then look at the add menu shown on your device instead of relying on the fixed button position in a screenshot from elsewhere. Keep an original copy of unrecognized content for reference, but do not repeatedly alter its encoding and hope it works. For the full first-time connection flow, return to the Getting Started Guide. Scanning is just an input method; you still need to select a server, check the routing mode and verify access.
05 / Update
Subscription update settings and troubleshooting
An update fetches the list again; it does not patch entries one by one
Updating a subscription requests its saved address again and refreshes the corresponding server list with the returned content. It does not check only the currently selected server, nor does it update the app itself. The remote list may change names, parameters, order or entry count, so changes after an update are possible. App updates are managed through the App Store; subscription updates take place in the client. They solve different problems and should not be confused.
Before updating from the subscription menu provided in the interface, confirm whether the action applies to one subscription or all of them. If troubleshooting a single source, update that subscription alone first and keep other groups for comparison. Note when you updated, whether entries changed and what error appeared; these observations do not require sharing the full address. After the update, check whether the currently selected entry is still there.
When to update manually and when to use automatic updates
Manual updates are useful for a first import, a change announced by the provider, a visibly outdated list or troubleshooting. Automatic updates suit subscriptions you have verified as stable and want to keep in sync with remote changes; use the available controls and intervals shown in the app. More frequent updates are not necessarily better: repeated requests cannot fix an invalid address and may increase load on the remote service. If nothing has changed, repeated refreshes are not needed to keep a connection working.
Device lock, background scheduling, the current network and app state can all affect when an automatic update actually runs. Setting an interval does not guarantee the device will complete a request at precisely that time. If the list has not changed, first check whether a fetch actually took place, then whether the remote response contained new content. If needed, update manually in the foreground and check the result rather than drawing conclusions from the automatic update switch alone.
Troubleshoot in stages: request, response and parsing
If a request cannot complete, check the device's network first, then verify that the address is complete and still valid. Do not start by deleting working entries or repeatedly changing DNS, Global Routing and the subscription address. Keep the current settings and change one condition at a time, noting the result. Failure on one network but success on another can help narrow things down, but check the error message before concluding that the remote address is invalid.
If you see a clear HTTP status error, record the status and time. Authentication-related responses usually call for checking the credentials in the address and account permissions. Stop repeated retries if requests are being rate-limited. Errors from the remote service need to be checked on the server side. A status code describes one stage; on its own, it does not prove that local server parameters are wrong. When reporting the issue, hide sensitive query parameters but include enough context about the error.
If the request succeeds but parsing fails, check whether the response has changed to a login page, maintenance notice or empty response. Being able to open the address does not mean the response contains a server list. If the name remains but the entries disappear, that does not mean every server failed at once. If the address has changed in validity or authorization, verify the latest information from your service provider. Do not try to work around a format problem by copying old page text or altering the encoding.
Verify the update and check local changes
After a successful update, check the selected entry, protocol type and at least one real access request. If the remote list removed the server you were using, select a replacement explicitly; do not assume the app will find the same entry by its old name. Check whether local renames or parameter changes were overwritten. Keep any changes you need long-term in a clearly labeled manual copy, understanding that it will not update automatically with the subscription.
A single failed update does not mean you need to rebuild all your subscriptions. Keep the existing working list, wait a reasonable interval before retrying and check for status information from your service provider. Record subscription-fetch failures separately from whether existing servers can connect. If the list updates but connections fail, continue with Latency and connection checks. Distinguishing fetching from using a server helps avoid repeating steps at the wrong stage.
06 / Groups
Organize multiple subscriptions, names and duplicate entries
Group by source, then identify entries by purpose
When managing multiple subscriptions, first make it clear who updates each server, rather than focusing on making the list shorter. Keep each subscription in its own group and use names that identify their purpose or source, without including access credentials. Make manually added entries distinguishable from subscription-generated ones. That way, when parameters change, you can update the right subscription or edit an individual entry without accidentally changing an entire group.
Use stable information in names, such as daily use, temporary checks or manual copy. Avoid putting a one-time test result in a long-term name; network results change. Remote server names may be restored during updates. If you need a local note, use a note feature supported by the interface or keep it in your own records. Do not rely on manual sorting within a subscription as the only way to identify an entry's purpose.
Names alone do not tell you whether entries are duplicates
Two entries with the same name may use different addresses, ports, authentication or transport settings. Entries with different names may use identical connection parameters. Before removing anything, compare Type, address, port, authentication method, TLS and transport options. Entries with different credentials may have different permissions even if they connect to the same host, so do not assume one can be deleted just because the addresses match.
Common causes of duplicates include scanning the same QR code repeatedly, pasting the same share link more than once, adding the same subscription twice and creating manual copies for testing. First determine whether the duplicates came from local imports or were already present in the remote list, then choose how to handle them. Locally created duplicates can be organized; similar entries in the subscription itself may return at the next update, so deleting them individually will not provide a lasting fix.
Sort to suit the task at hand
When organizing, keep group boundaries intact, then review names or test results within the relevant group. Sorting by latency is useful for a comparison at that time; sorting by name helps find a known entry; manual order works for a small list you maintain yourself. After sorting, check which entry is selected instead of remembering “the first one.” Remote updates or changes to filters can move a server to a different position.
If the list is large, start with the subscription you are currently using and leave the other groups as they are. Finish naming, checking and verifying one group before moving on, so you do not change all your troubleshooting clues at once. If the interface supports search or collapsing groups, use those features to narrow the view; they usually affect display, not deletion. Confirm the scope before removing any entries.
Keep a minimal record of your setup
Consider recording each subscription's display name, whether automatic updates are enabled, whether you have a manual copy and the result of your latest hands-on check. You do not need to duplicate complete authentication details in your notes; just record where to find the original information. If you need to keep the original address, store it in a protected personal location, separate from routine notes. Names, update times and test results are not substitutes for original recovery information.
Before organizing, check whether Config refers to the affected entries by server name or policy group. Deleting or renaming an entry can break those references, especially in manually maintained policies. A subscription group is not the same as a policy group in Config: the former organizes sources, while the latter determines connection policies. Putting a server in a subscription group does not make a rule use it; check the current configuration as well.
Before deleting entries in bulk, keep a recoverable copy and test the process on a few confirmed duplicates. Return to Home to check the remaining entries and current selection before deciding whether to expand the cleanup. If you cannot tell whether an action affects one entry or a whole group, cancel it for now. The goal is to remove ambiguity, not combine every subscription into one long list with no traceable source.
For a practical order for organizing multiple existing subscriptions, see Organize multiple subscriptions: groups, sorting and duplicate cleanup. After organizing, keep a clear path for everyday use and a record that points to the original information. That is more reliable for future updates and device migration than relying on a fixed list position.
07 / Connectivity Test
Latency tests, sorting and verifying connections
Know what the test measures first
Connectivity Test shows how a request responds under the selected test method. Different methods cover different stages: some mainly reflect the connection to a server, while others also request a specified test target. Interpret results in light of the current settings; a single number is not the same as the loading speed of every website. Results from different targets, device networks or test times are not directly comparable.
Before testing, confirm the device itself can access the internet and check the current routing mode and selected server. To compare servers, use the same network, test method and target, and test them close together in time. Do not switch networks while comparing results or draw stability conclusions by mixing a Wi-Fi result with one from another network. The more consistent the test conditions, the more useful the comparison.
What numbers, timeouts and fluctuations mean
A lower result means the response was faster in this test; it does not guarantee better large-file transfers, long-lived connections or performance in a particular app. A timeout only means the test did not complete under the current conditions and within the allotted time. The cause may involve the server, test target, name resolution or network path. If only a few entries fail, compare them with successful entries. If all fail, check the conditions they share before re-entering every server's parameters.
Retest an isolated result, but avoid running tests constantly. Brief network congestion, a device switching connections or remote server load can all cause fluctuations. Test again when conditions are stable and see whether the result is consistent. For everyday use, consistently completing real requests is usually more useful than one exceptionally low number. Use test results as one factor in your choice, not the only reason to exclude other entries.
Verify real access in stages
Select a server and turn on the connection switch. Follow the system prompt to authorize the VPN configuration, then test a familiar, ordinary website or app. A connected status on the device confirms only the corresponding connection state; it does not guarantee remote authentication, rule matching and target responses are all working. Check the app's connection status, error messages and actual request results separately. Leaving the switch on is not proof that the connection is fully usable.
With Global Routing set to Config, a rule may route the test target through DIRECT. A website opening successfully does not necessarily prove that the selected server handled the request. Check the relevant rules in the current configuration and any available connection records to confirm which policy matched. If you temporarily change the routing mode for comparison, note the original setting and restore it afterward. Do not leave a routing change in place after troubleshooting a single issue.
If latency tests succeed but a website will not open, continue by checking DNS resolution, server authentication, rule routing and the target site's response separately. First test different ordinary targets through the same server, then compare with the device network to narrow down the cause. A DNS issue calls for checking resolution settings, not repeatedly refreshing the subscription. See DNS troubleshooting when latency is normal but websites won't load; avoid rebuilding subscriptions and overwriting Config at the same time.
Confirm your selection after sorting
Sorting by test results changes the display order, but does not necessarily change which server is in use. After sorting, check the selection indicator to confirm the entry, then connect. Subscription updates, switching groups or running another test can all change list positions, so do not identify a server as “the first one” or “the third one.” When reporting an issue, use a redacted name and type rather than its position.
If only one app fails, check its rules, domains and connection records before blaming the entire subscription. If only one server fails, check its parameters and remote status. In comparisons, change one condition at a time and record the time, test method, error type and result. These notes can distinguish persistent failures from temporary fluctuations and reduce repeated changes to settings you have already verified.
08 / Backup & Restore
Deletion, backups and restoring on a new device
Confirm what you are deleting and its scope
Deleting a single server, a subscription group or Config are different actions. A deleted entry from a subscription may return at the next update. Deleting a subscription may remove the locally saved address used to retrieve its list. Deleting Config affects rules and related settings. Read the confirmation prompt and make sure you understand what will be removed. Do not clear the list as a first response to connection problems or delete items in bulk without the original information.
Removing a subscription from the client usually changes what is saved locally; it does not revoke remote access. If a real address or authentication details have been exposed, revoke or replace the credentials using the management options provided by your service provider, then update your local records. Deleting a QR code image, server entry or exported file does not invalidate credentials someone else already obtained. Handle a credential leak separately from organizing your list.
Back up each kind of data separately
Recoverable materials should distinguish at least the original subscription address, manually entered server parameters and current Config. A subscription can retrieve the list currently provided remotely, but may not restore names or parameters you changed manually. A configuration file can preserve rules but may not include every server or subscription. After exporting a type of data, check exactly what it contains instead of assuming the backup is complete based on its filename.
When saving information through an export or share option provided by the app, pay attention to the destination and access permissions. Store exported files containing credentials in protected storage you control; do not leave them scattered in chat as ordinary attachments. Backup names can identify a device and purpose, but should not include full passwords. After saving, confirm that the file opens and contains the expected data, and keep recovery notes with it so it is not left as an unidentifiable file.
On a new device, get the app first, then restore your data
On a new iPhone or iPad, get Shadowrocket from the App Store first. For checking purchases, accounts and purchase eligibility, see Restore a previous purchase. Check the App Store listing for system requirements. Restoring a purchase only restores access to the app; it does not automatically restore all locally stored server parameters. Once the app opens, restore subscriptions, manual entries and Config from your own backups rather than assuming they will all appear automatically.
If you use an iCloud-related sync feature provided by the app, check the actual sync scope and status on both devices. Being signed in to the system account does not mean every type of app data has synced; seeing Config does not prove that all manually added servers have been restored. Keep the old device until you have verified the new one. Before confirming that the sources and contents match, avoid importing manually and triggering sync repeatedly, which may create duplicate or hard-to-identify copies.
A sensible order is to restore existing subscriptions on the new device and fetch their lists, then restore any manually maintained entries, import and select Config, and finally check Global Routing. If the configuration refers to specific names or policy groups, verify that those items exist. Connect and test ordinary access, then check routing for important apps. A successful restore means the setup works and matches your needs, not just that the lists look similar to those on the old device.
Clean up old data only after verification
After migrating, keep the old device and original backups for comparison. Confirm that the new device can update subscriptions, use manual entries and apply Config correctly before deciding what to do with the old data. If the old device remains in use, understand how synced deletions work before cleaning it up; changes made on one device may propagate to others. Avoid renaming everything, replacing rules and changing subscription addresses all at once during migration, or it will be difficult to trace the differences.
Periodically check that your backups still match the current setup, especially after changing subscription addresses, manually adjusting authentication or editing Config. You do not need to keep piles of duplicate copies for every test, but retain a clear recoverable baseline and necessary change notes. When old credentials expire, include related backups in your cleanup so you do not restore stale parameters and bring old problems back to the device.
For a fuller device migration walkthrough, see Move Config and restore it on a new device. To repeat the full connection workflow, return to the Getting Started Guide. For help verifying where to buy the app, see How to verify the official App Store listing. A sound management workflow closes the loop: know where your information came from, what you are updating, and what has been tested, and keep personal backups that can restore your setup.