Shadowrocket Subscription and Server Management

01 / Import an updatable server list

Subscribe: entry point and object relationships

First, distinguish subscriptions, servers, and configuration files

A subscription is a server list that can be fetched repeatedly. A server is a specific connection entry. A configuration file determines how requests match rules and which policy handles them. These objects are related, but they are not interchangeable. A successful subscription update means the list was fetched and parsed; it does not mean a selected server can connect. A working server does not mean the current configuration routes traffic as expected. Before troubleshooting, identify which object you are working with to avoid mistaking a rule issue for a subscription issue.

Check Home for the current server and its subscription, and use Config to manage configuration-related items. In this guide, go to Config and look for Subscribe. If your platform combines subscription setup with the plus button on Home, choose the Subscribe type in Add Server. The entry point may differ between platforms. Check the form type and URL field instead of relying on the location of a button on another device.

Check what the link is for before adding it

Get the subscription URL from your service provider. Read the instructions that came with it and confirm that it is a Shadowrocket server subscription, not an account management page, help page, or full rule configuration. A URL opening in a browser does not mean Shadowrocket can parse its response as a server list. If the link contains authentication parameters, copy the entire URL, including everything after the question mark. Do not include punctuation added by a messaging app.

https://example.com/sub?token=xxxx

In the Subscribe form, enter a recognizable name and the complete URL, then save and update. Keep your network stable during the first import. When it finishes, return to Home and check for server entries, whether the number is in line with your existing information, and whether the names are readable. There is no fixed number that defines success: the list can change when the service updates it. Refer to your authorized content and the provider's instructions.

Use the results to identify where the process failed

If no servers appear after saving, first check whether the app actually requested the URL. A saved name with an empty list may indicate a failed request, an empty response, or an unrecognized format. For authentication errors, check whether the link was replaced, expired, or copied incompletely. If the response is a web page, confirm that you have the subscription endpoint rather than a login page. Repeatedly adding the same failing URL creates empty groups to clean up without changing the result.

If some entries appear but others are missing, check whether the missing entries use a protocol and parameters supported on your platform, and whether the subscription was meant to return only part of the list. Keep the entries that imported correctly, note what failed, and compare them with your existing server details. Do not fill in unknown passwords, ports, or transport parameters just to make the list look complete. These fields must match the server; guessed entries may save but still fail to connect.

If server entries exist but connections behave unexpectedly, do not immediately delete and recreate the subscription. Select one entry, run the single-server test described later, and then check Global Routing. This lets you verify list retrieval and traffic handling separately. For a step-by-step first setup, see the setup tutorial. The remaining sections cover fields, updates, and organization for troubleshooting specific issues.

02 / Verify an individual server entry

Add Server fields and protocol parameters

Select Type first, then enter the original details

Manual entry is useful when you have the complete server details and need to troubleshoot one entry in isolation. Open Add Server from Home, select Type, then fill in the fields shown for that type. The protocol selection changes the form, so do not fill in the default form and switch types afterward. Before saving, compare each field with the original details. Check especially for spaces, line breaks, full-width colons, and ports accidentally entered in the address field.

Address is usually the server's domain or address; enter the port separately in Port. Do not add a web protocol prefix to Address. A domain and a path used to access a web page are different things; enter the path in the relevant transport settings. For IPv6, distinguish the bracket notation used in share links from what the form requires. If the form has separate address and port fields, do not paste an address-and-port string into one field. A name is only for identification; it cannot fix connection parameters.

Similar fields are not interchangeable

Shadowsocks requires both the encryption method and password to match; the same password alone does not make a configuration correct. VMess and VLESS commonly use a UUID, but sharing a UUID does not make the protocols interchangeable. The transport and its additional fields must also match. Enter Trojan authentication in the corresponding password field. For HTTP and SOCKS5, check whether authentication is enabled. Leave optional fields at their defaults unless the provider has supplied values; do not copy a seemingly complete set of settings from another entry.

TLS, SNI, Host, and Path each serve a different purpose. Address determines where the connection is made. SNI specifies the server name during the TLS handshake. Host may be part of the application-layer request, and Path identifies the relevant transport path. They may sometimes have the same value, but that does not make it a general rule. Preserve different values when they appear in the original details. Do not force them to match for a tidier form, or use a redirect domain shown on a web page as SNI.

Hysteria2, WireGuard, and other types may require specific authentication or key details. Add them only when the subscription provides the parameters or you have the complete server configuration. If you are unsure about a field, check what it means against the original details. Entering arbitrary text just to save the form creates an entry that looks complete but does not prove the protocol is configured correctly. See the protocol overview for basic differences between protocols.

Find field errors by changing one thing at a time

After saving, select this server and test it. For now, avoid changing DNS, rules, and connection mode at the same time. If the test fails, check in this order: address resolution, port connectivity, authentication, and transport parameters. An incorrect address often causes a resolution error; a port or network issue may cause a timeout; authentication and handshake failures require checking the specific error. An error narrows down the possibilities but does not replace checking each field. For example, a refused connection may mean the port is wrong or the server is not listening.

If you need to correct a parameter, change one item at a time and note the reason, old and new values, and result. Give manual entries a clear name such as “Manual” so they are easy to distinguish from subscription entries. If you are testing a parameter, copy the entry and edit the copy first. Once it works, decide whether to keep the change. Do not edit subscription entries directly if you are unsure how updates work; a refresh may restore the original value and make the troubleshooting results hard to compare.

03 / Create entries from existing content

Scan QR Code and import from clipboard

First, identify what the QR code contains

A QR code is a way to carry text, not a protocol in its own right. It may contain a single server share link, a subscription URL, or a regular web page. After opening Scan QR Code, check the recognized content and the object to be saved against your original details. A successful scan only means the text in the image was read. It does not prove the destination is available or that the authentication details are still valid. A scan prompt is not proof that a server has connected.

When scanning from another screen, fit the entire QR code in view and avoid glare, obstruction, and excessive zoom. If the app requests camera access, grant permission when prompted for scanning. If access was denied, check the app's permissions in system settings. If you already have an image of the QR code, use the image recognition option in the current interface when available. If your platform does not offer one, importing the original text is usually more direct than repeatedly adjusting the image.

If the scan recognizes a subscription URL, save it as a Subscribe source, not as a server Address. If it recognizes a single server, check Type, Address, Port, and authentication fields after saving. A QR code normally contains only the encoded content. Do not assume the app has read nearby text shown in the image as well. Pay particular attention to passwords, notes, or transport requirements printed below the code; they may not be included in it.

Preserve the exact text and encoding when importing from the clipboard

Clipboard import is useful when you have copied a complete share link. Copy the link itself from the original message, then use the clipboard import option shown on Home or in the add menu. If the system asks for permission to paste, allow it after confirming the clipboard contains what you just copied. If the expected entry does not appear, first check whether another copy action replaced the clipboard contents. A failed import does not necessarily mean the protocol is unsupported; the clipboard may contain only a title or explanatory text.

Messaging apps may wrap long links across lines on screen, but a visual line break is not always an actual line break. After copying, check whether the text contains real line breaks or spaces that could interrupt parsing. Check that the protocol prefix is present, that there is no extra punctuation at the end, and that rich text has not replaced the link with a display name. If you cannot verify the copied text, get it again from the original rather than guessing how to reconstruct the missing part.

For bulk text imports, first confirm that the current entry point supports multiple records, then use clearly structured content. Pasting an entire message with a title, explanations, and several links can cause misidentification or import only the first entry. Start with one entry and verify its fields before importing the rest. If you already imported the same set, check the current list before trying again. This avoids mistaking duplicates for new servers from a subscription update and makes later testing and sorting easier.

Check three things after importing

First, verify the entry type: make sure a Subscribe source was not saved as a single server, and that a single server was not saved as a regular URL. Second, verify key fields, especially the password, UUID, SNI, and transport path. Third, check the source or group the entry belongs to and make sure it did not end up in a different subscription. Once these three checks are complete, test the connection. Separating text recognition from actual connectivity makes it easier to locate the problem.

If a scan shows an unfamiliar domain or parameters that do not match the original details, stop before saving and check the source. Subscription links are part of your access credentials and should not be forwarded to public groups or submitted to public recognition pages. When troubleshooting, you can describe the issue, such as “the QR code scans but saves as an empty entry,” without sharing the full content. If you need to show an image, cover the QR code itself; covering only nearby text does not hide the link encoded in the pattern.

For the entry points supported by the four import methods, see the subscription import guide. If the number of entries does not match after importing, return to Chapter 1 and check the subscription object. If only one entry fails, use Chapter 2 to check its parameters instead of repeatedly scanning the same image and creating duplicates.

04 / Understand the text structure

Share link formats and the boundary between links and Config

A protocol prefix only tells you where to start

Share links usually start with a protocol prefix and then carry the address, authentication, transport parameters, and notes. Each protocol uses a different encoding format, and even links with the same prefix may express parameters differently. Recognizing the prefix helps you choose an import method, but it does not confirm that the whole link is valid. After importing, review the fields to make sure they match your original details. Ignored parameters can leave an entry visible even when it cannot connect as expected.

Query parameters in a link often specify the transport, encryption, or other settings; the part after the hash is commonly a note. Notes with non-ASCII characters, spaces, or special characters may be percent-encoded, and authentication details may use Base64. Do not decode text just to make it easier to read and then paste it back, or encode already encoded content again. Characters can mean different things in different positions, so an unnecessary change can alter the structure of the entire link.

Do not use subscriptions, share links, and rules interchangeably

A subscription URL points to content that can be updated. A single share link usually describes one server, while Config describes behavior beyond the connection itself. When you receive an HTTPS URL, use the accompanying instructions to determine what it returns instead of always adding it through Subscribe. Text containing section names and rule lines is not a batch of server links. These objects can work together, but they have different storage locations and update mechanisms. Choosing the wrong entry point will not convert one type of content into another.

[General]
bypass-system = true

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

This rule snippet illustrates the syntax and contains no server authentication details. DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches address ranges, and FINAL handles requests that have not matched earlier rules. Rules are generally evaluated from top to bottom, and the first match determines how a request is handled. Put more specific matches before broad fallback rules. PROXY in this example requires an available proxy selection; writing the policy name does not automatically add a server.

In Global Routing, Config, Proxy, and Direct correspond to configuration-based routing, proxying, and direct connections. With Config, troubleshoot the rules in the current configuration. With Proxy, first check that the selected server works. With Direct, requests do not automatically use a server just because one exists in the list. When testing a subscription, note the current routing mode too; the same list can produce very different results in different modes.

Check the exposure of credentials before sharing

A server share link may contain a full password or UUID, while a subscription URL may allow repeated access to the list. Turning content into a QR code, shortening its display name, or encoding it does not make it less sensitive. When transferring details between your own devices, use a controlled method and make sure the receiving device is trusted. For help, share the protocol type, error message, and redacted fields instead of posting a complete working entry in a public screenshot.

If the fields differ when you import a link through different entry points, keep the original text and compare both parsed results. First check for truncation, escaping, or encoding changes, then confirm that the platform recognizes the relevant parameters. Do not assume every missing field means the link is invalid, and do not delete unfamiliar query parameters without a reason. Understanding each change is more important than making a long link that saves successfully. If you are unsure, check the format against the original details.

05 / Manage list changes

Subscription update settings and recovery from failures

Treat an update as a controlled replacement

A subscription update requests the source again, parses its response, and refreshes related entries. It does not retest every server or update the Shadowrocket app. The server may add, remove, or rename entries, which the app handles according to its own matching behavior. Before updating, identify which details come from the subscription and which you changed yourself. Pay particular attention to notes, the currently selected entry, and names referenced by rules so you can tell whether changes are expected.

Start with a manual update to confirm the content can be retrieved reliably, then consider the automatic update options available on your platform. A shorter interval is not always better. Frequent requests will not fix an incorrect URL and may trigger request limits at the source. If automatic updates are not available, refresh manually as needed. Whichever method you use, leave time to check the results before an important use. Avoid changing the source and updating a large list while you need to keep a connection running.

Four things to check before and after updating

Before updating, note the source name, currently selected server, any manual changes, and the network state. Afterward, check for a success message, look for obvious list changes, confirm the selected entry still exists, and run a single-server connection test. A changed entry count is not necessarily an error, but stop if the list suddenly becomes empty or many names look wrong. Keeping the original source and a backup is more useful for diagnosing whether a change came from the server or your device than immediately deleting and recreating the subscription.

If you edited parameters on a subscription entry, an update may overwrite them. For changes you need to keep long term, create a separate manual entry, note its purpose, and keep the original subscription entry for comparison. Do not assume a field will always be preserved because one update happened not to overwrite its note. Behavior can vary by field and platform. Confirm it with a controlled update rather than experimenting across many entries at once.

Troubleshoot in stages: retrieval, authentication, and parsing

If an update times out, first confirm that the device's network is working. Then check whether the subscription request depends on a proxy path that has stopped working. The path used to fetch a subscription may differ from the one used for regular web browsing; check the relevant settings on your platform. You can try another network in a controlled test, but do not change the network, rules, and source URL all at once. Otherwise, even a successful update will not tell you which change fixed the problem.

For authentication failures or access denied, check that the URL is complete, authentication parameters have not been reset, and the source still accepts your account. If you see a request-rate warning, stop refreshing repeatedly. Wait an appropriate amount of time and follow the source's instructions. If the response is a login page, notice page, or empty content, the app may report a parsing error. This is different from a server in the list timing out. Troubleshoot the subscription request itself; changing a server's port will not fix it.

If a source used to update but can no longer be parsed, check whether its response format changed and whether a newly copied link points to a different kind of endpoint. Saving a web page as a local file does not make it a valid server list, and you should not assemble fields arbitrarily from other formats. Keep the original error, the network conditions, and whether all sources fail or only one. This is usually more useful than repeatedly reinstalling the app. If just one source fails, troubleshoot that source rather than clearing all subscriptions.

Check configuration references after updating

A server name change may affect how you identify or select entries. If you use custom policies, check their references as well. If an entry is still visible but traffic suddenly uses a different route, check both the currently selected server and Config rather than relying on the name at the top of the list. For rules you use regularly, document their dependencies and keep a restorable copy of the configuration. Handling subscription and rule maintenance separately reduces the risk of one update causing changes in several places.

06 / Keep source ownership clear

Organizing multiple subscriptions and managing local changes

Names should show ownership, not just location

When managing multiple subscriptions, give each source a stable, distinctive name. Use names that reflect your own purpose or where the details came from. There is no need to put the full URL in the title, and never put passwords or authentication parameters in a note. Server notes identify individual entries; you can keep the original name and add a short description. Source names and server names serve different levels of organization. Keeping them distinct makes it easier to find failures, handle duplicates, and remove an entire group accurately.

When organizing for the first time, do not merge all sources immediately. Check each one for update success, approximate list contents, and independent manual entries before deciding how to order them. The same server name in two sources does not mean the entries are identical, and different names do not prove their addresses and authentication differ. To identify duplicates, compare the source, protocol, address, port, and key parameters. Do not delete entries in bulk based only on their displayed names, or change authentication details just to standardize names.

Separate remotely maintained entries from local ones

Subscription entries are maintained by their source; manual entries are for independent details you know. If you need to adjust a subscription entry temporarily for testing, copy it or create a clearly labeled duplicate and note why you changed it. This keeps the original available for comparison and prevents an update from overwriting test parameters. Remove unused copies promptly after testing; otherwise, they can get mixed in with working entries and make the list look larger but harder to maintain.

Use grouping, favorites, and sorting only when those options are actually available on your platform. If there is no separate favorites feature, clear notes and source names are enough for basic organization. Do not confuse the visual order of the list with policy priority: moving a server to the top usually does not make Config select it automatically. Requests are routed according to the current selection, Global Routing, and the policies in the configuration; check each separately.

Check differences before removing duplicates

The same address and port can be used with different protocols, authentication, or transport settings, so matching those two fields alone does not prove entries are duplicates. Conversely, importing the same share link repeatedly can create multiple entries with different notes. Before cleanup, compare key fields and check whether the entries belong to the same source. If they are duplicates, prefer the entry that updates normally and has clear ownership. If you made a manual correction, document why before deciding which copy to delete.

If a source cannot update temporarily but its existing servers still work, keep it for now and note its status instead of removing it immediately. If you have stopped using a source, check whether any configuration still references its server names and whether the current connection depends on it. Organize only when you have a way to recover, and keep “temporarily failing,” “duplicate,” and “no longer needed” separate. Working one group at a time is slower than selecting everything, but it leaves a clear history of what changed.

Keep rules consistent across devices; do not chase identical-looking lists

The same subscription may look different on different devices because of platform capabilities, display options, or local manual entries. Aim for correct sources, matching key parameters, and clear selection logic, not identical row counts and ordering. After migrating, check the original source first, then individual entries, and finally Config. If a protocol's fields differ on the target platform, compare the current interface with the original details. Do not treat a screenshot from another device as the definitive form layout.

07 / Interpret test results

Connectivity Test, latency, and sorting

Know what the test actually measures

A latency result comes from a specific test; it is not a permanent measure of a server's overall quality. Some tests check port connectivity, while others use the proxy to access a destination. The test protocol, target address, current network, and number of concurrent tests all affect the result. Before using Connectivity Test or a list test, check the options and settings available on your platform. Results are comparable only when the test conditions are similar. Sorting values from different kinds of tests can lead to the wrong conclusion.

A reachable port does not guarantee that authentication will succeed or that a website can be opened through the proxy. A test target that does not respond does not necessarily mean all access will fail either. If a test returns a result but a web page does not load, check authentication, TLS, transport settings, DNS, and rules. If a test fails but access works, check the test target and its route. Do not delete an entry based on a single symbol; first confirm which part of the connection the test covers.

Make comparisons repeatable

Use a known-working entry as a baseline, then test other candidates on the same network and around the same time. Avoid heavy downloads or sync tasks during testing because they can affect the results. Batch tests can narrow down the choices, but running many at once adds load to your network and the server. If a result looks unusual, retest a small number of candidates individually. A low latency result only means that the target responded quickly at that moment; it does not prove higher sustained throughput.

After switching between Wi-Fi and mobile data, the previous order may no longer apply because the network path and resolution environment have changed. Instead of keeping a fixed “fastest” list, keep a few candidates for clear purposes and retest when your network conditions change. To record test conditions, note the network type, test method, and general result. Do not include full addresses or authentication details in public notes. Reproducible observations are more useful for troubleshooting than an isolated result.

Sorting and selecting are different actions

Sorting by latency changes the display order; do not assume it selects a different server. After sorting, return to Home and check which entry is selected before testing access. If the configuration uses a policy group or another selection method, check which entry that policy points to. The first row, the selected entry, and the server used by a rule may be three different things. Confusing them can make it seem as though selecting a faster entry had no effect.

To test rule-based routing, start with Proxy to verify the selected server's basic connectivity, then return to Config and check which rule matched. Direct can help you compare direct and proxy access, but direct access working does not prove the server works. After switching modes, check the current routing mode and remember to restore your original settings when testing is done. See feature details for more about Global Routing and diagnostics, or revisit the tutorial troubleshooting steps if your first connection fails.

Keep enough diagnostic details to identify the issue

For further troubleshooting, note whether all entries or just some fail, whether the issue occurs during an update or a connection, and whether it happens only on a particular network. Keep the original error text with sensitive details removed. Do not just write “it won't connect,” and do not share a complete working link to prove there is a problem. If the same entry works on another device, compare the saved parameters and current mode on both devices instead of resetting everything immediately. Compare differences first, then change one thing at a time.

08 / A maintenance process you can recover from

Delete, back up, and restore across devices

Confirm the object and scope before deleting

Deleting a server entry, a subscription source, or Config has different effects. If a deleted server entry is still maintained by a subscription, it may return on the next update. Whether deleting a source also removes its entries depends on the confirmation prompt. Deleting a configuration may change rule behavior even if the server list remains. Before proceeding, read the object name and confirmation details. Do not assume every cleanup button does the same thing, especially when the current connection depends on that object.

If you only want to stop using a source temporarily, check whether your platform offers a suitable disable or display option. If not, keep the source and label its purpose rather than removing it just to shorten the list. Before deleting it, confirm you still have the original details and a way to restore them. Deleting a link does not revoke its credentials. If a link has been exposed, removing it from your device will not stop others from using it; reset the relevant credentials through the original service's management channel.

Back up at least three kinds of data

First, back up subscription sources that can be fetched again. Second, back up independent manual entries with their complete parameters. Third, back up Config, rules, and any necessary selection relationships. Saving only the subscription URL does not preserve manual entries or rules; exporting rules alone does not include server passwords. When using the export or backup feature provided by your platform, read its documentation to confirm what it includes. After exporting, check that the file exists, has a recognizable name, and can be imported through the corresponding option on the target platform.

Backup files may contain passwords, UUIDs, keys, or subscription authentication parameters. Store them somewhere you control with appropriate access protection. A familiar file extension does not make a backup safe to share publicly as a help document. Do not mix backups with public screenshots, work files, or temporary transfer files. When transferring them between your own devices, verify the recipient and that the content arrived intact, then remove temporary copies you no longer need to reduce how widely credentials are stored.

Restore in order: source, entries, then configuration

When moving to another device, first install and open the app, then import your backup. The iPhone and iPad app is a one-time $2.99 purchase on the App Store; the Mac, Windows, Android, and Linux versions are free. See the download guide for platform options and installation steps. You do not need to overwrite all settings just to restore a subscription. First check whether any existing data on the new device needs to be kept, so you do not lose independent manual entries.

After restoring, check the source names and update each one manually to confirm its URL still works. Next, verify the key parameters of independent servers, then check Config and policy selection. An old backup can restore a previous local state, but it cannot guarantee that a remote service still accepts old credentials or that a server that was later changed still exists. A successful restore means the sources update, the entries you need connect, and the rules behave as required now—not that the list simply looks the way it used to.

Verify a backup with a small-scale restore

Before a major change, save a clearly labeled backup, then modify only one set of items. When possible, test the import without affecting your current setup rather than waiting until a device is lost to try restoring for the first time. If your platform does not make separate testing easy, at least check what the export includes, that the file is readable, and that the original details are complete. Keep a restore sequence you can follow. A useful backup preserves the objects you need; having more files is not the goal.

For long-term maintenance, use a consistent sequence: back up, make changes, update, test, and document. Handle one clearly defined issue at a time. After a successful change, leave a brief note; if it fails, restore the last known-good state. A one-time app purchase is not a service plan, and app purchase records cannot replace server detail backups. Use the contents at the top of this page to find the relevant section: Subscribe and updates for source issues, fields and tests for an individual connection, and this chapter for migration and cleanup.

Back to the top of the manual ↑ View the quick-start tutorial →