01 · Subscribe: Adding a Subscription for the First Time
Subscribe manages an address that can be used to retrieve a server list again; it is not a server itself. Once the returned content is recognized, it becomes server entries in the app. That means “subscription saved,” “list downloaded,” and “server connected” are three separate stages. When troubleshooting, first identify which stage failed. This avoids repeatedly changing protocol settings when an address is invalid, or mistaking a problem with one server for a failed subscription import.
Confirm what you’re adding before saving
Get the subscription link from your provider and make sure it is the complete address—not an account page, an instructions page, or a single server’s details. Keep the query parameters after the question mark; they may contain access credentials. Don’t trim the end just because the link is long, or treat an ellipsis shown by a messaging app as part of the address. Check the beginning and end after copying, and remove any accidentally included quotation marks, line breaks, or spaces. Don’t change the address’s capitalization or encoding.
From the add option on Home, open Add Server and choose Subscribe or the subscription option shown in your app. Paste the link into the address field and add a note that makes its purpose easy to identify. Return to the list after saving and check for the subscription group and its server entries. Layouts vary by platform. If you can’t find an option with that name, make sure you’re editing a subscription, not filling out a protocol form that asks for a single server address and port.
Check the first import in two stages
First check the retrieval result: does the list appear, do the server names look reasonable, and are the protocol types recognized? Then check the connection: select an entry, review its required fields, run a test, and try an actual connection. A visible list only means its contents were read; it says nothing about server status, credential expiry, routing, or your local network. A subscription name or server note is just a label, not proof of location, performance, or availability.
If the list is empty after saving, keep the original address for now rather than deleting the subscription. Check that your current network can reach it, and look for a login page, permission error, or other explanatory text in the response. Opening a page in a browser doesn’t mean the returned content is a server list the app can use. If you need to contact your provider, include the import time, error message, and network type. Never post the complete link publicly; it may contain sensitive information.
A subscription link may function as an access credentialDon’t include complete subscription links in screenshots, public notes, or shared clipboard histories. To demonstrate the format, use example.com and clearly fictional values—not a real account address.
How subscriptions, servers, and configurations differ
A subscription maintains server entries, each server entry describes a connection endpoint, and rules in Config determine how requests are handled. These work together but don’t replace one another: importing a subscription doesn’t configure rules, and switching configurations won’t fix an expired password. If a rule refers to a specific name, make sure that name exists in the current list. A successful subscription update alone doesn’t prove the rule’s target is valid.
After your first import, note a few basics: the subscription label, network used during import, whether the list was retrieved, and the name of one server you actually tested. Don’t include passwords or the full address. If something goes wrong later, compare it with this baseline before deciding whether to retrieve the subscription again or inspect an individual entry. To get connected quickly for the first time, return to the quick-start guide. Use this chapter’s checks when the results don’t match expectations.
02 · Add Server: Manual Fields and Protocol Boundaries
Add Server lets you turn existing server details into a connection entry. Before entering them manually, get the protocol name, server address, port, authentication details, and any required transport and TLS settings. An address and port alone are usually not enough. Match each field to the information from your provider; don’t put the same details into any protocol just because several forms have a password or key field. Choosing the wrong type can cause the handshake to fail even if the form saves successfully.
Enter the endpoint first, then authentication and transport settings
Choose the exact protocol type, then enter the server address. The address field usually accepts only a domain name or IP address—not a protocol prefix, web path, or port. Enter the port in its separate field. If your provider supplied a complete share link, import it rather than splitting it by hand and risking missing parameters. Don’t substitute a domain for an IP address, or vice versa: DNS resolution, certificate checks, and server-side routing may depend on the original name.
Next, enter the authentication details. Shadowsocks requires the encryption method and password used by the server; Trojan uses a password and usually requires checking TLS settings; for VMess and VLESS, verify the UUID and other connection options. Enter an HTTP or SOCKS5 username and password only if the server requires authentication. Don’t use your account login password as the server password, or copy credentials from a subscription link into a protocol authentication field unless the instructions explicitly call for it.
| Parameter group | What to check | Common mistake |
|---|---|---|
| Endpoint | Server address and port | Including a path or port in the address field |
| Authentication | Password, UUID, and encryption method | Reusing credentials across different protocols |
| TLS | TLS | Assuming SNI is always the same as the address |
| Transport | Transport type, Host, and Path | Missing the path or changing its capitalization |
| WireGuard | Keys and network settings | Confusing the local and remote keys |
Distinguish SNI, Host, and server address
The server address determines where to connect. SNI specifies the target name during the TLS handshake; some transport types also use Host and Path. These values may match, or they may intentionally differ. Don’t substitute one for another just because they look like domain names. Slashes, capitalization, and query strings in Path may also affect server-side matching. Enter the values exactly as provided. If a required value is missing, ask your provider rather than guessing.
If certificate verification fails, first check the device time, SNI, target domain, and whether they match the certificate. Then confirm that you’re connecting to the expected endpoint. Disabling verification shouldn’t be a routine fix; it changes how the connection’s identity is checked. If the instructions mention a special certificate setup, first clarify what the server requires. Hysteria2 and WireGuard have their own fields, so don’t assume every input works like a Trojan field.
After saving, troubleshoot one variable at a time
Save one entry with a clear note, then check four basics: protocol, address, port, and authentication. If something is wrong, change one group at a time and record what happens before and after. If you change the password, SNI, and transport type together, you won’t know which change fixed the connection. Describe test results precisely—“connection timed out,” “authentication failed,” or “TLS error”—rather than just “doesn’t work.” That makes it easier to choose what to check next.
If you manually copied the details from a subscription, note that this is a local copy. If your provider changes the password, port, or transport settings, the copy may not update with the subscription, so check it yourself. For WireGuard fields, see WireGuard Parameters Explained. If you’re unsure about an option, leave its default in place and check whether the server requires a change. Defaults help avoid unsupported changes, but they don’t replace complete settings from your provider.
03 · Scan QR Code and Import from Clipboard
QR code and clipboard imports are just different ways to enter data; the app still needs to recognize what the data contains. A QR code might hold a server share link, a subscription address, a regular web page, or other text. The clipboard might contain a heading, instructions, and several links. Don’t judge an import only by whether a confirmation appeared. Check the type, number, and fields of the new entries to make sure they match the original information.
Check the full process before and after scanning
When using Scan QR Code, grant camera permission if prompted and fit the entire code in the viewfinder. Avoid cropped edges, glare, or compressed images with unreadable details. If your current app can scan from an image, use a clear original image; there’s no need to upload the QR code to an external website. Passwords and subscription credentials in a QR code are just as sensitive as readable text. Don’t share them publicly because they’re hard to read at a glance.
After scanning, check the recognized content or the form before saving: is it Subscribe or a server entry for a specific protocol? Do the address and note look right? Are any fields missing? If the scan opens a web page, don’t assume the subscription has been imported; first check how that page relates to the actual address. If the code can’t be scanned, ask the person who provided it for the same content as text and try importing it from the clipboard. This helps distinguish an image-quality problem from a content-format issue.
Keep only the content you need in the clipboard
When copying text, select only the complete link, not surrounding instructions such as “click here.” If the system asks to access the clipboard, decide whether to allow it as part of an import you actually intend to perform. If you can’t continue after denying access, use the manual paste option instead; there’s no need to change protocol settings. Check for line breaks in the link: a displayed wrap is different from an actual inserted line break, which can split one link into two.
Preserve the original separators between multiple server links; one link per line is usually easiest to review. Test one link first, then import the rest in a batch to reduce cleanup if the format is wrong. When copying from rich text, documents, or chat messages, watch for full-width punctuation, invisible characters, and a trailing period. Don’t make blanket substitutions: symbols in passwords and encoded parameters may be valid parts of the link.
The import method doesn’t determine whether an entry can be updatedA server entry imported from a QR code is usually just a copy of its settings at that moment. Only an item saved as a subscription with its address retained can be used to retrieve a server list again.
Handling duplicates, missing fields, and permissions
Repeated import attempts may create duplicate entries, but matching names don’t prove the contents are identical. Before deleting anything, compare its source, protocol, address, and port; then check authentication and transport settings locally if needed. Entries with different notes may still connect to the same endpoint. If you’re unsure, keep the entry you’ve already tested, give the new one a clear note, and test it before tidying up. This helps avoid deleting the only working entry by mistake.
Some fields being blank after import doesn’t necessarily mean the app lost data: the original link may not include them, or its format may not be recognized. Compare the entry with the complete information from your provider, fill in required fields first, and don’t infer a protocol from the name. If the camera won’t open, check system permissions; if text can’t be read, check the clipboard and paste option; if fields are missing, investigate the format and settings. Separating permission, recognition, and connection issues avoids unnecessary steps.
After importing, clear sensitive clipboard contents according to your security practices and check whether cross-device clipboard access or third-party keyboard history sync is enabled. Store original details in a protected location if you need to keep them; don’t rely on leaving them in the clipboard. For platform permission prompts or connection problems after import, check the relevant FAQ. Don’t grant broader ongoing permissions just to get past a single prompt.
05 · Subscription Updates and Overwrite Handling
Updating a subscription means requesting its address again and letting the app process the returned server information. It’s different from updating Shadowrocket or reconnecting to the current server. An update may add entries, change settings, or remove old entries; check the results in your current app to see how it handled them. Don’t assume every local change will be preserved, or that an update will automatically fix every problem with an existing connection.
Protect local changes before updating
Before updating, note which server and routing mode you’re currently using. If you changed a password, transport setting, or note on a subscription entry, record what you changed and why. For important changes, use a clearly labeled separate copy rather than burying them in a subscription-managed entry. Separate copies need manual maintenance, so create them only when there’s a specific need. Avoid keeping a hard-to-track duplicate of the entire subscription list.
After a manual update, check the subscription status first, then review changes to the server list. A successful retrieval doesn’t mean every previous entry is still there or that the currently selected one still works. If the server you used has disappeared, check whether your provider removed or renamed it, then test a replacement. Don’t overwrite new settings with arbitrary values just to keep an old name: rules or automatic selections may still depend on how that entry is identified.
Set a retrieval schedule that fits how often things change
If your current platform and app provide an automatic update option, set it based on how often your provider makes changes and how you use your device. Background tasks depend on system scheduling, network availability, and power-saving settings; a scheduled time isn’t a guarantee of an update at that exact moment. Before an important session, you can update manually and check the result. Avoid repeated requests in a short period, which may trigger access limits and turn a normally successful retrieval into a failure.
If an update fails, check whether the local network is online, then whether the subscription domain is reachable, its credentials are still valid, and the response looks as expected. Some addresses depend on the current network route, so results may differ after switching networks. Distinguish “can’t retrieve the list” from “servers in the list can’t connect”: the first concerns the retrieval path; the second concerns connection endpoints. Saved entries may still work, but that doesn’t mean a new list was retrieved successfully.
Keep the current entries after a failureUntil you know the address is invalid or its contents are wrong, don’t delete all your entries to deal with a failed update. Preserve what works and identify which stage failed first.
Recognize overwrites, renames, and unexpected content
If a note reverts to its original name after an update, that entry may still be managed by the subscription. If the order changes, check whether the list order was updated or a previous test changed the sorting before assuming entries were replaced. Identify important servers by source, protocol, address, and port—not by name alone. Authentication and transport settings may also change. Compare sensitive fields locally; don’t send screenshots showing complete before-and-after details.
If an update suddenly adds many unfamiliar entries or changes the protocol types across the list, stop and check the subscription address and returned content. You may have selected the wrong subscription, the address may have been altered, or your provider may have changed its output. Don’t accept unexpected content as a normal update until you’ve confirmed the cause. Restore from known original information rather than choosing a seemingly similar address from an old message.
After a bulk update causes problems, check in this order: list retrieval, field details, a single-server test, then actual access. Record the result at each step. The app version and subscription content are maintained separately. To check how to get the app, see the downloads page; reinstalling isn’t a substitute for troubleshooting a subscription. Knowing what did and didn’t update helps you decide whether to restore settings, select a different entry, or contact your provider.
06 · Naming, Grouping, and Organizing Multiple Subscriptions
When managing multiple existing subscriptions, make them easy to identify instead of simply trying to shorten the list. Subscription names, server notes, connection endpoints, and policy targets in a configuration are different layers. Confusing them can lead to deleting working entries or discovering that a renamed entry no longer matches a rule. Organize around clear sources and purposes, with changes you can track. Don’t rely on colors, symbols, or location labels in names to indicate what an entry does.
Set naming conventions for subscriptions and manual entries
Name subscription notes for your own purposes—for example, daily use, testing, or a temporary migration—and record what they refer to in your personal notes. Don’t put a full account name, password, or subscription credentials in a note; it may appear in lists, exports, and screenshots. Keep server notes focused on the details needed to identify an entry rather than listing every protocol setting. A concise, distinct name is easier to spot; long notes may be truncated on narrow screens and make it easier to choose the wrong entry.
Clearly distinguish manually entered records, local copies with changes, and subscription entries. For example, use consistent purpose prefixes in notes and identify each source type in your backup notes. After an update, you’ll know which entries are managed by their source and which need your own review. If the app offers grouping, use it to reduce clutter. If it doesn’t, clear notes and a separate index without sensitive information can serve the same purpose. Don’t assume every platform has the same management options.
When removing duplicates, compare entries—not just their names
Two entries with the same name may come from different subscriptions or use different authentication or transport settings. Two entries with different names may point to the same address and port. To find duplicates, compare the source and protocol first, then the endpoint, and check authentication and transport settings locally if needed. Even identical endpoints may not be interchangeable: the server may distinguish connections by credentials or request name. If you’re unsure, mark possible duplicates for review instead of deleting them in bulk.
Adding the same subscription address twice can make it look as though you have more servers and make update results harder to understand. Compare the complete addresses locally, but don’t put sensitive links into a public comparison tool. If two subscriptions are exact duplicates, keep the clearly labeled, tested one. Check the current selection and any configuration references before removing the other. After cleanup, update the remaining subscription and test an actual connection to confirm it still maintains its list independently.
| Item | Main purpose | Risk when organizing |
|---|---|---|
| Subscription | Maintains a remote collection of servers | Deleting it may remove the update source |
| Server entry | Stores specific connection settings | May delete an endpoint you’re currently using |
| Local copy | Preserves independent changes | Settings may not follow changes from the source |
| Configuration reference | Specifies a rule or policy target | Renaming or deleting may leave the target unavailable |
Organize entries and change rules in separate steps
First finish naming and organizing entries by source, then verify the connection before changing references and policies in the configuration. If you deduplicate, rename, update, and edit rules all at once, it’s hard to tell which change caused a problem. Configurations that refer to servers by name need checking after a rename to make sure the target still exists. For rules that use a general policy name, confirm that it now selects the server you expect, not an earlier selection.
Keep a short change note when organizing: which subscription you kept, which duplicate source you removed, which manually entered entries need review, and which connection you tested afterward. Don’t include passwords or complete links. You can mark entries as temporarily inactive and delete them after confirming the backup can be restored. The goal is to make the next problem easy to trace, not simply to minimize the list. A few clearly useful alternatives are easier to maintain than many duplicates with unknown sources.
07 · Connectivity Test, Latency, and Sorting
Connectivity Test and other latency tests show how a connection performs under specific conditions; they don’t rate every capability of a server. Tests may use different targets, connection stages, and timeouts, so results are comparable only when the method, device network, and timing are similar. A lower number doesn’t mean faster downloads, and a timeout alone doesn’t prove a server is down. Understand what a test measures before sorting or choosing entries.
Build a test sample under consistent conditions
Before testing, make sure your local network is working and use the same network type for each entry. Don’t test some over Wi-Fi and others over mobile data. Check the test method and target used by the current app; if you change them, note the difference. Start with a few candidates, then repeat the test after a short interval to see whether results are stable. Large concurrent tests may be limited by your device, network, or server, so don’t treat a single batch as conclusive.
If every entry fails, check factors they have in common first: device connectivity, test target, current routing mode, and system-level connection restrictions. If only one entry fails, inspect its address, port, and authentication. If the same entry performs differently on different networks, record the difference rather than rebuilding every configuration. This step-by-step approach separates an endpoint problem from a shared test-condition issue and prevents you from clearing a usable list based on one failed result.
Distinguish latency, throughput, and actual requests
Latency measures how long a specific interaction takes; throughput reflects sustained transfer capacity. Actual access also depends on the destination site, DNS, rule matching, and server load. After a test passes, select the entry and visit a normal destination you need to use to confirm that requests follow the expected route. If only one app has a problem, check its connection method and rules rather than declaring the entire server entry unusable. Existing long-lived connections may also take time to reflect a change.
You can briefly compare Global Routing modes while troubleshooting. Config applies the rules in your configuration; Proxy and Direct can help you compare proxy and direct paths. But testing changes the scope of traffic handling, so be clear about what you’re testing and restore your usual settings afterward. Don’t judge a rule solely by whether a page opens: Direct may reach the same destination. Check the current mode and available connection details to confirm where the request went.
Sorted results are a reference for the conditions at test timeSorting by latency doesn’t guarantee that future requests will be faster or automatically switch the current connection. After sorting, confirm which server is selected and check the current routing mode.
Sorting, selecting, and recording problems
Before sorting by test results, check which entries are included: one subscription, all entries, or a filtered set of candidates. Mixing scopes can obscure where entries came from. After sorting, check whether the current selection changed. If the app only changes display order, select and test an entry yourself. For entries that repeatedly time out, mark them or add them to a review list rather than deleting them immediately; the cause could be a temporary network issue, test target, or provider maintenance.
When documenting a problem, record the test method, network type, error, whether the subscription list can be retrieved, the result of an actual visit, and any recent settings changes. Don’t publish complete logs to explain the issue: they may contain domains, addresses, request details, or authentication data. Review them locally and share as little as possible. If you need help from your provider, describe the symptoms well enough to identify the problem, and send sensitive credentials only through their normal protected channel.
If latency looks normal but speeds are slow, check the local network, protocol settings, route, and server status in stages. See How to Troubleshoot Slow Speeds in Stages. Change just one condition at a time—for example, switch networks or try one other existing entry—to make a useful comparison. The goal is to identify what affects the connection, not chase the lowest number in one test. Reproducible results and clear notes are usually more useful than repeatedly sorting the list.
08 · Deletion, Backup, and Restore Verification
Before deleting anything, identify what it is: a single server entry, an entire subscription, a configuration file, or the app itself. Each has a different impact. Some entries can be restored by retrieving a subscription again; manually entered settings and local changes may have no other source. Seeing a subscription name doesn’t mean you have a backup, and a screenshot of a list can’t restore authentication or transport settings. A reliable backup makes clear what it contains, what’s missing, and how to verify it.
List the information you need to keep
Separate at least four types of data: subscription addresses, independent server settings, configuration files, and local preferences related to how you use the app. A subscription address can retrieve a list again, but there’s no guarantee your provider will return the same content later. A server share link may not include local changes; a configuration file may contain rules but no usable servers. Before backing up, check what the current platform actually exports. Don’t assume the file contains everything based on its name or size.
After using the app’s export or share option, check the file and what it’s for in a protected location, and record its source and restore order. Treat text, QR codes, and files that contain authentication information as sensitive. Don’t distribute them through public cloud links, shared documents, or ordinary photo albums. If you use cloud storage, apply account protection and access controls you trust. Convenience doesn’t replace checking who can read a backup.
Delete in stages, using the smallest scope needed
Before deleting a server entry, switch to another tested entry and check whether your configuration refers to the one you plan to remove. If you’re deleting a subscription group, read the confirmation prompt and find out what will happen to associated servers. Don’t assume that deleting a subscription removes only its address or that retained servers can still update automatically. If you’re unsure, test the behavior on a low-impact item first, then handle important subscriptions and configurations.
A server maintained by a subscription may reappear after you delete it because it’s still in the remote list. That doesn’t necessarily mean deletion failed; it reflects the difference between local deletion and remote list management. If you just don’t want to use it for now, add a clear note, select another entry, or use the management options available in your app. Don’t damage the entire subscription to keep an entry from returning, and never save an address with its credentials altered to make it invalid.
A backup is complete only when it can be restoredConfirming that a file exists is only the first step. Also check protocol fields, configuration references, the current selection, and actual access. An export-success message alone doesn’t prove the restore process is complete.
Restore connectivity first, then automation
Start with the smallest working setup: restore a subscription or one independent server, verify its settings, and test actual access. Then restore Config and its rules, and finally check automatic connection settings such as On Demand. If something goes wrong, this order helps identify whether the cause is the connection details, a rule reference, or an automation condition. Permissions and network environments may differ across devices, so always test on the new device even if the same file worked on the old one.
After restoring, check that the subscription can update, the current server still exists, local copies are still needed, and rules don’t refer to outdated names. If a backup contains an old password, restoring it won’t make that password valid again. If subscription credentials have changed, get the current details from your provider. Keep old backups for reference, but don’t overwrite newer settings without checking; doing so can bring back problems you’ve already fixed.
If you suspect that a subscription address or server credentials have been exposed, deleting the entry from your device won’t invalidate the exposed information. Follow your provider’s normal process to replace or revoke the credentials, then update the app and backups. Delete old files you no longer need and keep a restore note without sensitive information. A routine of saving before changes, verifying afterward, and cleaning up only when confirmed is more reliable than accumulating exports you can’t identify. For more common questions, see the FAQ; for your first connection, see the Getting Started guide.